{"_id":"@cns-labs/agreements-mcp-server","_rev":"3-539b110c009deee714a16547ba6d7cd0","name":"@cns-labs/agreements-mcp-server","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@cns-labs/agreements-mcp-server","version":"0.1.0","keywords":["agreements-protocol","mcp","model-context-protocol","api","typescript"],"author":{"name":"Agreements API Maintainers"},"license":"MIT","_id":"@cns-labs/agreements-mcp-server@0.1.0","maintainers":[{"name":"devs-cns-labs","email":"dev@cnslabs.io"}],"homepage":"https://github.com/CNSLabs/agreements-api-sdk/tree/main/packages/agreements-mcp-server#readme","bugs":{"url":"https://github.com/CNSLabs/agreements-api-sdk/issues"},"bin":{"agreements-mcp-server":"dist/stdio.js","agreements-mcp-server-http":"dist/http-main.js"},"dist":{"shasum":"baecbeeeb92f0822a0831771bdc26fcdc5428666","tarball":"https://registry.npmjs.org/@cns-labs/agreements-mcp-server/-/agreements-mcp-server-0.1.0.tgz","fileCount":57,"integrity":"sha512-TeO6kmUFdgSYWano/civRv6/fgI4qHLLmj3FA0SmS0oOOSFlcRNVOqHrTx7naVyUodLdENShoDoDEFDwVoHfXA==","signatures":[{"sig":"MEUCIFzSzeOvP1vkVSS9EUU36IWV6V085CHUt9JZ2p7r7dH6AiEA/3m1FBlDjgf1y9ddvjPbrtHeRKmvhu/C805sv7pqRVw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":195934},"main":"./dist/index.js","type":"module","_from":"file:cns-labs-agreements-mcp-server-0.1.0.tgz","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./manifest":{"types":"./dist/manifest.d.ts","import":"./dist/manifest.js"}},"scripts":{"lint":"tsc --noEmit -p tsconfig.json","test":"pnpm run build && node --test test/*.test.mjs","build":"tsc -p tsconfig.json","start":"node dist/http-main.js","start:stdio":"node dist/stdio.js"},"_npmUser":{"name":"devs-cns-labs","email":"dev@cnslabs.io"},"_resolved":"/private/var/folders/wn/_d0_dlnn6lj42yqnczjd6hfw0000gn/T/ee211dbb8f067ba507aad7f51d71e694/cns-labs-agreements-mcp-server-0.1.0.tgz","_integrity":"sha512-TeO6kmUFdgSYWano/civRv6/fgI4qHLLmj3FA0SmS0oOOSFlcRNVOqHrTx7naVyUodLdENShoDoDEFDwVoHfXA==","deprecated":"Moved to @shodai-network/agreements-mcp-server. Install that instead; this package is no longer updated.","repository":{"url":"git+https://github.com/CNSLabs/agreements-api-sdk.git","type":"git","directory":"packages/agreements-mcp-server"},"_npmVersion":"10.8.2","description":"Model Context Protocol server for the Agreements API, built on @cns-labs/agreements-api-client","directories":{},"_nodeVersion":"20.17.0","dependencies":{"zod":"^3.25.1","viem":"^2.43.0","@modelcontextprotocol/sdk":"^1.29.0","@cns-labs/agreements-api-client":"^0.3.1"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"~5.6.2","@types/node":"^20.10.6"},"_npmOperationalInternal":{"tmp":"tmp/agreements-mcp-server_0.1.0_1781898748625_0.09647180501631847","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-06-19T19:52:28.502Z","modified":"2026-08-06T17:46:43.540Z","0.1.0":"2026-06-19T19:52:28.775Z"},"bugs":{"url":"https://github.com/CNSLabs/agreements-api-sdk/issues"},"author":{"name":"Agreements API Maintainers"},"license":"MIT","homepage":"https://github.com/CNSLabs/agreements-api-sdk/tree/main/packages/agreements-mcp-server#readme","keywords":["agreements-protocol","mcp","model-context-protocol","api","typescript"],"repository":{"url":"git+https://github.com/CNSLabs/agreements-api-sdk.git","type":"git","directory":"packages/agreements-mcp-server"},"description":"Model Context Protocol server for the Agreements API, built on @cns-labs/agreements-api-client","maintainers":[{"name":"devs-cns-labs","email":"dev@cnslabs.io"}],"readme":"# @cns-labs/agreements-mcp-server\n\n[Model Context Protocol](https://modelcontextprotocol.io) server for the Agreements API. Configure Shodai as a remote Streamable HTTP MCP server and the full agreement lifecycle — author, validate, preflight, deploy, submit inputs — becomes callable as MCP tools.\n\nThe server is a pure consumer of the public `/v0` API via [`@cns-labs/agreements-api-client`](../agreements-api-client). It holds no business logic and stores no credentials: every tool call forwards the caller's API key to the Agreements API gateway, which enforces auth, entitlements, and metering.\n\n## Hosted endpoint\n\nStateless Streamable HTTP: `POST` only, JSON responses, no sessions. Use this hosted setup contract:\n\n```text\nConfigure Shodai as a remote Streamable HTTP MCP server.\n\nURL:\nhttps://developers.shodai.network/mcp\n\nAuth:\nAuthorization: Bearer $SHODAI_API_KEY\n\nKey shape:\ncns_pk_...\n\nTool environment:\ntestnet\n\nUse this value as the environment argument on API-calling tools. API keys only work in the environment where they were created.\n```\n\nHosted API-calling tools require an `environment` argument: `testnet` or `production`. API keys only work in the environment where they were created, so a testnet key must be used with `environment: \"testnet\"` and a production key must be used with `environment: \"production\"`. OAuth and JWT bearer tokens are not supported.\n\nGet an API key from the [Developer Portal](https://developers.shodai.network). Full client setup, tool reference, and signing guidance: [Connect via MCP](https://docs.shodai.network/sdks/connect-via-mcp).\n\n## Run locally (stdio)\n\n```json\n{\n  \"mcpServers\": {\n    \"shodai-agreements\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cns-labs/agreements-mcp-server\"],\n      \"env\": {\n        \"AGREEMENTS_API_KEY\": \"YOUR_API_KEY\",\n        \"AGREEMENTS_API_ENVIRONMENT\": \"testnet\"\n      }\n    }\n  }\n}\n```\n\nStdio environment variables:\n\n| Variable | Use |\n| --- | --- |\n| `AGREEMENTS_API_KEY` (or `API_KEY`) | API key used for tool calls. Required. |\n| `AGREEMENTS_API_ENVIRONMENT` | `testnet` (default) or `production`. |\n| `AGREEMENTS_API_BASE_URL` | Explicit gateway origin override. Wins over the environment. |\n| `AGREEMENTS_SIGNER_PRIVATE_KEY` | Optional local permit signer for write tools (dev/testnet only). |\n| `INFURA_PROJECT_ID` | Infura project ID used to derive RPC URLs for the built-in Linea, Sepolia, and Base agreement chains. |\n| `AGREEMENTS_RPC_URL`, `AGREEMENTS_RPC_URL_<chainId>` | Optional RPC overrides used when preparing or signing permits. |\n\n## Tools\n\nMost tools call the public `/v0` API through the TypeScript client and carry MCP behavior annotations (`readOnlyHint`, `destructiveHint`). A few tools perform more than one operation to keep signing and deployment safe.\n\nOn the hosted endpoint, every API-calling tool below requires `environment: \"testnet\" | \"production\"`. Local stdio mode uses the fixed environment from `AGREEMENTS_API_ENVIRONMENT` instead.\n\n| Tool | Wraps | Scope |\n| --- | --- | --- |\n| `list_agreements` | `GET /v0/agreements` | `agreements.read` |\n| `get_agreement` | `GET /v0/agreements/{id}` | `agreements.read` |\n| `get_agreement_document` | `GET /v0/agreements/documents/{documentId}` | `agreements.read` |\n| `get_agreement_state` | `GET /v0/agreements/{id}/state` | `agreements.read` |\n| `get_input_history` | `GET /v0/agreements/{id}/inputs` | `agreements.read` |\n| `validate_agreement` | `POST /v0/agreements/validate-template` | `agreements.write` |\n| `preflight_deployment` | `POST /v0/agreements/validate` | `agreements.write` |\n| `deploy_agreement` | `POST /v0/agreements/validate`, then `POST /v0/agreements/deploy-with-permit` | `agreements.write` |\n| `submit_input` | `POST /v0/agreements/{id}/input` | `agreements.write` |\n| `prepare_deployment_typed_data` | `POST /v0/agreements/validate`, then local EIP-712 payload construction with a chain nonce read | `agreements.write` |\n| `prepare_input_typed_data` | `GET /v0/agreements/{id}`, then local EIP-712 payload construction with a chain nonce read | `agreements.write` |\n\nResources are discoverable with `resources/list`:\n\n| Resource | URI |\n| --- | --- |\n| `simple-example-agreement` | `agreements://examples/simple-agreement.json` |\n| `complex-example-agreement` | `agreements://examples/complex-agreement.json` |\n| `authoring-guide` | `agreements://docs/author-agreement-json.md` |\n| `docs-index` | `agreements://docs/index.md` |\n\nPrompt: `author_agreement` (business description → agreement JSON).\n\n## Signing custody modes\n\nDeploys and input submissions require EIP-712 permits. Three supported modes:\n\n1. **Pre-signed permit** — the agent or host app holds a wallet, signs externally, and passes `signer`/`deadline`/`signature` to `deploy_agreement` or `submit_input`.\n2. **Prepare typed data, sign externally** — call `prepare_deployment_typed_data` / `prepare_input_typed_data` to get the exact EIP-712 payload, sign it with any EIP-712-capable signer, then call the write tool. For deployments, pass the returned `normalizedInitValues`, `normalizedParticipants`, and `normalizedObservers` back to `deploy_agreement` with the signature.\n3. **Local environment signer (stdio only)** — set `AGREEMENTS_SIGNER_PRIVATE_KEY` and write tools sign locally. Dev/testnet pattern; the hosted endpoint never signs with server-side keys.\n\nMinimal hosted flow: read `simple-example-agreement`, call `validate_agreement`, `preflight_deployment`, `prepare_deployment_typed_data` with `environment`/`agreement`/`chainId`/`signerAddress` and intended deployment context, sign externally, then call `deploy_agreement` with the same `environment`, `displayName`, matching `docUri`, normalized deployment fields, and permit fields. For inputs, call `prepare_input_typed_data` with `environment`/`agreementId`/`inputId`/`values`/`signerAddress`, sign externally, call `submit_input` with the same `environment`, then reread state and input history.\n\nHosted MCP receives signed permit fields only, never private keys. Private-key environment signing is for local stdio development and testnet automation only.\n\n## Self-hosting\n\n```bash\nnpm install @cns-labs/agreements-mcp-server\nagreements-mcp-server-http   # Streamable HTTP on PORT (default 3905), endpoint /mcp\n```\n\nHTTP environment variables: `PORT`, `HOST`, `MCP_PATH`, `AGREEMENTS_API_TESTNET_BASE_URL`, `AGREEMENTS_API_PRODUCTION_BASE_URL`, and optional local `AGREEMENTS_API_BASE_URL` for single-origin testing.\n\nA `Dockerfile` is included for container deployments. `GET /healthz` serves as the health endpoint.\n\n## Development\n\n```bash\npnpm install\npnpm --filter @cns-labs/agreements-mcp-server build\npnpm --filter @cns-labs/agreements-mcp-server test\n```\n\nVerify interactively with the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector):\n\n```bash\nnpx -y @modelcontextprotocol/inspector@latest --cli http://localhost:3905/mcp \\\n  --transport http --method tools/list --header \"Authorization: Bearer $SHODAI_API_KEY\"\n```\n\nPin `@latest`: older Inspector versions do not support `--transport`/`--header` for URL targets.\n\n## License\n\nMIT — see [LICENSE](./LICENSE). Note this package is MIT-licensed individually; other packages in this repository are licensed under Apache-2.0.\n","readmeFilename":"README.md"}