Shodai Agreements

Servidor MCP para crear, coordinar y ejecutar acuerdos: compromisos, depósitos en garantía y flujos de trabajo de decisión multipartes entre humanos, agentes y organizaciones.

GitHub
2

Documentación

Shodai Agreements SDK + MCP

Shodai convierte definiciones de acuerdos en flujos de trabajo de coordinación legibles por máquina y verificables para humanos, productos y agentes de IA. Los acuerdos incluyen términos legibles además de participantes, entradas válidas, estados, transiciones e historial.

Este repositorio brinda soporte a desarrolladores que usan el SDK de TypeScript, agentes o herramientas que usan MCP, y la aplicación de referencia canónica de Shodai construida sobre el SDK.

Comienza aquí

NecesidadInicio
Entender ShodaiInicio de Shodai · Documentación para desarrolladores · Aplicación de demostración
Obtener accesoPortal de desarrollo / Claves API
ConstruirElegir SDK vs MCP · Inicio rápido de MCP · Inicio rápido del SDK de TypeScript · Flujo de trabajo de extremo a extremo

MCP alojado: https://shodai.network/mcp es el endpoint de ejecución MCP de Shodai Agreements. Los clientes compatibles con OAuth se conectan mediante inicio de sesión en el navegador y consentimiento para acceso a testnet. El endpoint usa Streamable HTTP, requiere un argumento de herramienta environment, admite claves API con ámbito de entorno como respaldo y no tiene custodia de claves privadas alojadas.

Paquetes y aplicaciones: @shodai-network/agreements-api-client · @shodai-network/agreements-mcp-server · agreements-api-playground · shodai-reference-app · oauth-connect-cli (shodai-oauth)

Por qué los desarrolladores usan Shodai Agreements

  • Estado de acuerdo compartido que humanos, aplicaciones y agentes pueden inspeccionar.
  • Próximas acciones deterministas a partir de estados, entradas, emisores y transiciones autorados.
  • Validación y verificación previa al despliegue antes de las firmas.
  • Autorización firmada EIP-712 para despliegue y entradas de participantes.
  • Historial de estados y entradas para recibos y monitoreo.
  • Menos orquestación repetida de contratos, indexación y trabajo de integración de flujos de participantes.

Elige tu camino

CaminoÚsalo cuandoPrimer éxito
MCP / herramientas de agenteUn agente o cliente compatible con MCP trabajará con acuerdos a través de Streamable HTTP alojado o stdio local.Autenticar, leer o listar donde esté permitido, validar un ejemplo, verificar previamente el despliegue y preparar datos tipados de despliegue.
SDK de TypeScriptEstás construyendo una aplicación o servicio en TypeScript.Autenticar, leer o listar acuerdos, validar un ejemplo, verificar previamente el despliegue y demostrar preparación para firma EIP-712 local.

Ambos caminos convergen en el mismo ciclo de vida de acuerdos. Después de que un inicio rápido funcione, ejecuta el flujo de trabajo de extremo a extremo.

Endpoint MCP alojado

Configura Shodai como un servidor MCP remoto Streamable HTTP:

URL:
https://shodai.network/mcp

Required API-calling tool argument:
environment: "testnet"

Inicia la conexión en un cliente compatible con OAuth y luego completa el inicio de sesión y consentimiento en el navegador de Shodai. El endpoint alojado anuncia el servidor de autorización de testnet, así que usa environment: "testnet" para esta conexión OAuth.

Los clientes sin soporte OAuth pueden enviar Authorization: Bearer cns_pk_.... Las claves API solo funcionan en el entorno donde se crearon; una clave de producción puede usar environment: "production". El MCP alojado nunca recibe claves privadas; las herramientas de escritura usan permisos EIP-712 firmados externamente o preparación de datos tipados.

Un GET de navegador ordinario a /mcp puede devolver 405 porque el endpoint espera solicitudes de protocolo MCP. Las superficies MCP en docs.shodai.network son solo para documentación y búsqueda; https://shodai.network/mcp es el endpoint de ejecución de Agreements.

Qué contiene este repositorio

Paquete o aplicaciónUbicaciónPropósito
@shodai-network/agreements-api-clientpackages/agreements-api-clientCliente REST tipado para la API de Agreements con ayudantes de firma de permisos viem.
@shodai-network/agreements-mcp-serverpackages/agreements-mcp-serverPaquete de servidor MCP local alineado con la superficie MCP de ejecución de Agreements alojada.
agreements-api-playgroundapps/agreements-api-playgroundAplicación Vite de referencia para experimentación con la API en el navegador y ejemplos de flujos de trabajo del SDK.
shodai-reference-appapps/shodai-reference-appImplementación de referencia full-stack React/Nest/Mongo para autenticación de plataforma de desarrolladores, uso de la API de Agreements, UX del ciclo de vida de acuerdos, firma, persistencia y reconciliación de webhooks.
oauth-connect-cli (shodai-oauth)apps/oauth-connect-cliCLI que conecta una aplicación OAuth pública a un usuario mediante authorization_code + PKCE, almacena una sesión renovable y llama a la API de Agreements como ese usuario.

Instala el SDK de TypeScript

La mayoría de los consumidores de TypeScript deberían instalar el paquete npm publicado en lugar de este monorepo:

npm install @shodai-network/agreements-api-client

Agrega viem si quieres los ayudantes integrados de firma de permisos para despliegue y envío de entradas:

npm install @shodai-network/agreements-api-client viem

Crea un cliente con un entorno Shodai nombrado:

const client = new ApiClient({
  environment: 'testnet',
  apiKey: process.env.AGREEMENTS_API_KEY,
});

La documentación de uso del SDK y del ciclo de vida de la API está en packages/agreements-api-client/README.md. Para opciones del constructor, métodos, ayudantes de firma, diagnósticos y exportaciones, consulta la referencia del cliente TypeScript.

Ejecuta MCP localmente

Usa el paquete MCP publicado para clientes stdio locales:

{
  "mcpServers": {
    "shodai-agreements": {
      "command": "npx",
      "args": ["-y", "@shodai-network/agreements-mcp-server"],
      "env": {
        "AGREEMENTS_API_KEY": "YOUR_API_KEY",
        "AGREEMENTS_API_ENVIRONMENT": "testnet"
      }
    }
  }
}

El modo stdio local usa AGREEMENTS_API_ENVIRONMENT; el MCP alojado usa el argumento de herramienta environment. Consulta packages/agreements-mcp-server/README.md para autoalojamiento, variables de entorno, herramientas, recursos, prompts y uso de Inspector.

Ciclo de vida de acuerdos

FaseSDK de TypeScriptMCP
Autorar JSON de acuerdoUsa artefactos JSON completos de acuerdos y ejemplos.Lee recursos de ejemplo o usa el prompt de autoría.
Validar estructuraclient.validateTemplate(...)validate_agreement
Verificar previamente el despliegueclient.validateDeployment(...)preflight_deployment
Preparar o firmar permiso de despliegueAyudantes de firma del SDK con viemprepare_deployment_typed_data y firma externa
DesplegardeployAgreementWithPermit(...) o client.deployWithPermit(...)deploy_agreement con campos de permiso firmados
Leer estadoclient.getAgreementState(...)get_agreement_state
Preparar o firmar permiso de entradaAyudantes de firma de entradas del SDKprepare_input_typed_data y firma externa
Enviar entradasubmitAgreementInputWithPermit(...) o client.submitAgreementInput(...)submit_input con campos de permiso firmados
Inspeccionar historialclient.listAgreementInputs(...)get_input_history

Para un recorrido guiado por validación, despliegue, envío de entradas firmadas, lecturas de estado e historial de entradas, usa el flujo de trabajo de extremo a extremo.

Entornos de la API de Agreements

El SDK prefiere un entorno nombrado en lugar de un host sin procesar:

const client = new ApiClient({
  environment: 'testnet',
  apiKey: process.env.AGREEMENTS_API_KEY,
});

Mapeos integrados:

  • testnet -> https://test-api.shodai.network
  • production -> https://api.shodai.network

Las claves API tienen ámbito de entorno. Usa una clave de testnet con testnet y una clave de producción con production.

El cliente aún admite baseUrl como anulación avanzada para proxies locales, pasarelas internas o despliegues no estándar. Continúa agregando /v0/* automáticamente.

Desarrollo local

# from the repository root
pnpm install
pnpm build
pnpm dev

El comando de desarrollo predeterminado inicia la aplicación de referencia de Shodai. Su backend usa por defecto http://localhost:4199 y su frontend usa por defecto http://localhost:5184/agreements/.

Detén la pila de desarrollo de la aplicación de referencia con:

pnpm dev:stop

Consulta apps/shodai-reference-app/README.md para los archivos de entorno local requeridos.

Ejecuta el playground de la API explícitamente con:

pnpm dev:playground

El playground usa por defecto http://localhost:5176. Si ese puerto ya está en uso, inicia el playground en otro puerto:

pnpm --filter agreements-api-playground exec vite --host 127.0.0.1 --port 4176

Para desarrollo local en el navegador, el playground prioriza el entorno y usa por defecto testnet. Usa el selector de entorno dentro de la aplicación para cambiar entre objetivos de API alojados testnet y production.

Comandos de validación opcionales específicos de paquetes:

pnpm --filter @shodai-network/agreements-api-client run lint
pnpm --filter @shodai-network/agreements-mcp-server test

Consulta apps/agreements-api-playground/README.md para la configuración completa del entorno.

Límites

El MCP alojado no guarda claves privadas. El OAuth de navegador del MCP alojado y el OAuth delegado directo de la API son rutas de conexión admitidas; los pagos x402 no son una ruta de configuración actual. Los acuerdos de Shodai no reclaman finalidad legal ni ejecución totalmente autónoma. Shodai no mueve valor sin entradas firmadas autorizadas.

Notas del proyecto de código abierto