Shodai Agreements

Servidor MCP para criar, coordenar e executar acordos: compromissos, custódia e fluxos de trabalho de decisão entre múltiplas partes, envolvendo humanos, agentes e organizações.

GitHub
2

Documentação

Shodai Agreements SDK + MCP

A Shodai transforma definições de acordos em fluxos de trabalho de coordenação legíveis por máquina e verificáveis para humanos, produtos e agentes de IA. Os acordos contêm termos legíveis, além de participantes, entradas válidas, estados, transições e histórico.

Este repositório apoia desenvolvedores que usam o SDK TypeScript, agentes ou ferramentas que usam MCP, e o aplicativo de referência canônico da Shodai construído sobre o SDK.

Comece Aqui

NecessidadeInício
Entenda a ShodaiPágina inicial da Shodai · Documentação para desenvolvedores · Aplicativo de demonstração
Obtenha acessoPortal do desenvolvedor / chaves de API
ConstruaEscolha entre SDK e MCP · Início rápido com MCP · Início rápido com SDK TypeScript · Fluxo de trabalho de ponta a ponta

MCP hospedado: https://shodai.network/mcp é o endpoint MCP de execução de acordos da Shodai. Clientes compatíveis com OAuth se conectam por meio de login no navegador e consentimento para acesso à testnet. O endpoint usa Streamable HTTP, exige um argumento de ferramenta environment, suporta chaves de API com escopo de ambiente como alternativa e não possui custódia de chaves privadas hospedadas.

Pacotes e aplicativos: @shodai-network/agreements-api-client · @shodai-network/agreements-mcp-server · agreements-api-playground · shodai-reference-app · oauth-connect-cli (shodai-oauth)

Por Que Desenvolvedores Usam Shodai Agreements

  • Estado compartilhado de acordos que humanos, aplicativos e agentes podem inspecionar.
  • Próximas ações determinísticas a partir de estados, entradas, emissores e transições autorados.
  • Validação e pré-verificação de implantação antes das assinaturas.
  • Autorização assinada EIP-712 para implantação e entradas de participantes.
  • Histórico de estados e entradas para recibos e monitoramento.
  • Menos orquestração repetida de contratos, indexação e infraestrutura de fluxo de trabalho de participantes.

Escolha Seu Caminho

CaminhoUse quandoPrimeiro sucesso
MCP / ferramentas de agenteUm agente ou cliente compatível com MCP trabalhará com acordos por meio de Streamable HTTP hospedado ou stdio local.Autentique, leia ou liste onde for permitido, valide um exemplo, faça a pré-verificação de implantação e prepare os dados tipados de implantação.
SDK TypeScriptVocê está construindo um aplicativo ou serviço TypeScript.Autentique, leia ou liste acordos, valide um exemplo, faça a pré-verificação de implantação e comprove a prontidão para assinatura EIP-712 local.

Ambos os caminhos convergem para o mesmo ciclo de vida de acordos. Depois que um início rápido funcionar, execute o fluxo de trabalho de ponta a ponta.

Endpoint MCP Hospedado

Configure a Shodai como um servidor MCP remoto Streamable HTTP:

URL:
https://shodai.network/mcp

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

Inicie a conexão em um cliente compatível com OAuth e conclua o login e o consentimento no navegador da Shodai. O endpoint hospedado anuncia o servidor de autorização da testnet, portanto use environment: "testnet" para esta conexão OAuth.

Clientes sem suporte a OAuth podem enviar Authorization: Bearer cns_pk_.... As chaves de API funcionam apenas no ambiente em que foram criadas; uma chave de produção pode usar environment: "production". O MCP hospedado nunca recebe chaves privadas; as ferramentas de escrita usam permissões EIP-712 assinadas externamente ou preparação de dados tipados.

Um GET comum de navegador para /mcp pode retornar 405 porque o endpoint espera solicitações de protocolo MCP. As superfícies MCP em docs.shodai.network são apenas para documentação e pesquisa; https://shodai.network/mcp é o endpoint de execução de acordos.

O Que Este Repositório Contém

Pacote ou aplicativoLocalizaçãoFinalidade
@shodai-network/agreements-api-clientpackages/agreements-api-clientCliente REST tipado para a API de Acordos com auxiliares de assinatura de permissão viem.
@shodai-network/agreements-mcp-serverpackages/agreements-mcp-serverPacote de servidor MCP local alinhado à superfície MCP de execução de acordos hospedada.
agreements-api-playgroundapps/agreements-api-playgroundAplicativo Vite de referência para experimentação da API no navegador e exemplos de fluxo de trabalho do SDK.
shodai-reference-appapps/shodai-reference-appImplementação de referência full-stack React/Nest/Mongo para autenticação de plataforma de desenvolvedor, uso da API de Acordos, UX do ciclo de vida de acordos, assinatura, persistência e reconciliação de webhooks.
oauth-connect-cli (shodai-oauth)apps/oauth-connect-cliCLI que conecta um aplicativo OAuth público a um usuário via authorization_code + PKCE, armazena uma sessão renovável e chama a API de Acordos como esse usuário.

Instale o SDK TypeScript

A maioria dos consumidores TypeScript deve instalar o pacote npm publicado em vez deste monorepo:

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

Adicione viem se quiser os auxiliares integrados de assinatura de permissão para implantação e envio de entradas:

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

Crie um cliente com um ambiente nomeado da Shodai:

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

A documentação de uso do SDK e do ciclo de vida da API está em packages/agreements-api-client/README.md. Para opções de construtor, métodos, auxiliares de assinatura, diagnósticos e exportações, consulte a referência do cliente TypeScript.

Execute MCP Localmente

Use o pacote MCP publicado para clientes stdio locais:

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

O modo stdio local usa AGREEMENTS_API_ENVIRONMENT; o MCP hospedado usa o argumento de ferramenta environment. Consulte packages/agreements-mcp-server/README.md para auto-hospedagem, variáveis de ambiente, ferramentas, recursos, prompts e uso do Inspector.

Ciclo de Vida de Acordos

FaseSDK TypeScriptMCP
Autorar JSON do acordoUse artefatos e exemplos completos de JSON de acordos.Leia recursos de exemplo ou use o prompt de autoria.
Validar estruturaclient.validateTemplate(...)validate_agreement
Pré-verificar implantaçãoclient.validateDeployment(...)preflight_deployment
Preparar ou assinar permissão de implantaçãoAuxiliares de assinatura do SDK com viemprepare_deployment_typed_data e assinatura externa
ImplantardeployAgreementWithPermit(...) ou client.deployWithPermit(...)deploy_agreement com campos de permissão assinados
Ler estadoclient.getAgreementState(...)get_agreement_state
Preparar ou assinar permissão de entradaAuxiliares de assinatura de entrada do SDKprepare_input_typed_data e assinatura externa
Enviar entradasubmitAgreementInputWithPermit(...) ou client.submitAgreementInput(...)submit_input com campos de permissão assinados
Inspecionar históricoclient.listAgreementInputs(...)get_input_history

Para uma execução guiada por validação, implantação, envio de entrada assinada, leituras de estado e histórico de entradas, use o fluxo de trabalho de ponta a ponta.

Ambientes da API de Acordos

O SDK prefere um ambiente nomeado em vez de um host bruto:

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

Mapeamentos integrados:

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

As chaves de API têm escopo de ambiente. Use uma chave de testnet com testnet e uma chave de produção com production.

O cliente ainda suporta baseUrl como uma substituição avançada para proxies locais, gateways internos ou implantações não padronizadas. Ele continua adicionando /v0/* automaticamente.

Desenvolvimento Local

# from the repository root
pnpm install
pnpm build
pnpm dev

O comando de desenvolvimento padrão inicia o Aplicativo de Referência da Shodai. Seu backend usa como padrão http://localhost:4199 e seu frontend usa como padrão http://localhost:5184/agreements/.

Pare a pilha de desenvolvimento do aplicativo de referência com:

pnpm dev:stop

Consulte apps/shodai-reference-app/README.md para os arquivos de ambiente locais necessários.

Execute o playground da API explicitamente com:

pnpm dev:playground

O playground usa como padrão http://localhost:5176. Se essa porta já estiver em uso, inicie o playground em outra porta:

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

Para desenvolvimento local no navegador, o playground prioriza o ambiente e usa como padrão testnet. Use o seletor de ambiente no aplicativo para alternar entre os alvos de API hospedados testnet e production.

Comandos opcionais de validação específicos do pacote:

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

Consulte apps/agreements-api-playground/README.md para a configuração completa do ambiente.

Limites

O MCP hospedado não mantém chaves privadas. O OAuth de navegador do MCP hospedado e o OAuth delegado direto da API são caminhos de conexão suportados; pagamentos x402 não são um caminho de configuração atual. Os acordos da Shodai não reivindicam finalidade legal ou execução totalmente autônoma. A Shodai não movimenta valor sem entradas assinadas autorizadas.

Notas do Projeto de Código Aberto