{"_id":"@buychat/mcp","name":"@buychat/mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@buychat/mcp","version":"1.0.0","description":"Model Context Protocol (MCP) server for BuyChat. Lets AI agents (Claude Desktop, Cursor, terminals) search, rank, and transact on the BuyChat marketplace via the Ed25519-signed Neural Commerce Protocol (NCP v1).","private":false,"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","bin":{"buychat-mcp":"dist/index.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^3.25.0","@buychat/ncp-sdk":"1.0.0"},"devDependencies":{"@types/node":"^20.11.0","typescript":"^5.7.0"},"keywords":["mcp","model-context-protocol","buychat","ncp","agent","marketplace","ai-agent","ed25519"],"engines":{"node":">=20"},"scripts":{"build":"tsc","dev":"tsc --watch","start":"node dist/index.js"},"_id":"@buychat/mcp@1.0.0","_integrity":"sha512-4ZXAMwzGkM7xD3G8AIeMTXuQOyJHokwIXWeVi+y1b8vL5aCqJC9ADMAVyNmttmgfjJLmPK5fus4CS2N8IPVAWQ==","_resolved":"/private/var/folders/kf/2sy6yhln6d5cpw9y9vt7rqbw0000gn/T/634c71856596a2ffd395a20faea0883d/buychat-mcp-1.0.0.tgz","_from":"file:buychat-mcp-1.0.0.tgz","_nodeVersion":"23.11.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-4ZXAMwzGkM7xD3G8AIeMTXuQOyJHokwIXWeVi+y1b8vL5aCqJC9ADMAVyNmttmgfjJLmPK5fus4CS2N8IPVAWQ==","shasum":"c22423afe2a923eeeb7534ae0a0832751a4b7e61","tarball":"https://registry.npmjs.org/@buychat/mcp/-/mcp-1.0.0.tgz","fileCount":22,"unpackedSize":90907,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIE67UPh00NM5jKwxFnVeM/t2j4hmNTHvarwxnN+RhuCSAiEA+A5WNRRE/HD0VfZRJtOe1924sZ3HgDsDt+73ePjjjWY="}]},"_npmUser":{"name":"xwordwide","email":"demianahuama@gmail.com"},"directories":{},"maintainers":[{"name":"xwordwide","email":"demianahuama@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_1.0.0_1783601382041_0.1771881392475505"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-09T12:49:41.859Z","1.0.0":"2026-07-09T12:49:42.175Z","modified":"2026-07-09T12:49:42.421Z"},"maintainers":[{"name":"xwordwide","email":"demianahuama@gmail.com"}],"description":"Model Context Protocol (MCP) server for BuyChat. Lets AI agents (Claude Desktop, Cursor, terminals) search, rank, and transact on the BuyChat marketplace via the Ed25519-signed Neural Commerce Protocol (NCP v1).","keywords":["mcp","model-context-protocol","buychat","ncp","agent","marketplace","ai-agent","ed25519"],"readme":"# @buychat/mcp\n\nA **Model Context Protocol (MCP)** server that lets AI agents — Claude Desktop,\nCursor, terminal agents, and anything else that speaks MCP — discover and shop\non the **BuyChat** marketplace.\n\nIt runs over the **stdio** transport and wraps the Ed25519-signed\n[Neural Commerce Protocol (NCP v1)](../ncp-sdk) via `@buychat/ncp-sdk`. No new\nbackend protocol — every call is a signed NCP request.\n\n```\nMCP host (Claude Desktop / Cursor)  ⇄  @buychat/mcp (stdio)  ⇄  NCP v1 (Ed25519)  ⇄  buychat.ng\n```\n\n---\n\n## Quick start\n\nAdd the server to your MCP host config.\n\n### Anonymous (discovery only)\n\n```json\n{\n  \"mcpServers\": {\n    \"buychat\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@buychat/mcp\"]\n    }\n  }\n}\n```\n\n### With an agent identity (unlocks transactions)\n\n```json\n{\n  \"mcpServers\": {\n    \"buychat\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@buychat/mcp\"],\n      \"env\": {\n        \"BUYCHAT_AGENT_ID\": \"agt_your_marketplace_id\",\n        \"BUYCHAT_AGENT_PRIVATE_KEY\": \"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\"\n      }\n    }\n  }\n}\n```\n\n- Claude Desktop config lives at\n  `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS).\n- Cursor: Settings → MCP → add the same `buychat` block.\n\n---\n\n## Configuration (environment variables)\n\n| Variable | Required | Default | Description |\n| --- | --- | --- | --- |\n| `BUYCHAT_AGENT_ID` | for signed tools | — | Your registered marketplace agent id. |\n| `BUYCHAT_AGENT_PRIVATE_KEY` | for signed tools | — | Ed25519 **PKCS8 PEM** private key. Inline `\\n` escapes are accepted. |\n| `BUYCHAT_AGENT_PRIVATE_KEY_FILE` | optional | — | Path to a `.pem` file (alternative to the inline key). |\n| `BUYCHAT_API_URL` | optional | `https://buychat.ng` | NCP base URL. |\n\nRegister an agent and obtain a keypair from the BuyChat developer surface\n(`/developers` → \"Register your agent\"). The same key the SDK signs with works\nhere.\n\n**Credential gating:** with no credentials the server registers the read /\ndiscovery tools only. With **both** `BUYCHAT_AGENT_ID` and a private key it also\nregisters the signed, transactional tools. (Set only one and it falls back to\nanonymous mode and warns on stderr.)\n\n---\n\n## Tools\n\n### Read / discovery\n\n| Tool | NCP mapping | Notes |\n| --- | --- | --- |\n| `list_vendors` | `GET /ncp/v1/marketplace/agents` | **Public** — works with no credentials. Lists marketplace agents/vendors with reputation badges. |\n| `search_products` | `POST /ncp/v1/search` (`NcpClient.search`) | Requires credentials (server signs the request). |\n| `rank_products` | `POST /ncp/v1/rank` (`NcpClient.rank`) | Re-rank candidate listing ids. Requires credentials. |\n| `recommend` | `GET /ncp/v1/recommendations` | Personalised for a principal the agent is authorized for. Requires credentials. |\n| `get_listing` | `GET /ncp/v1/listings/:id` | Full listing detail + trust + price intelligence. Requires credentials. |\n\nOnly `list_vendors` is genuinely anonymous; the other NCP read endpoints require\na signed agent identity server-side. Called without credentials they return a\nclear \"set your env vars\" message instead of a raw 401.\n\n### Signed / transactional (require credentials)\n\n| Tool | NCP mapping | Notes |\n| --- | --- | --- |\n| `track_order` | `GET /ncp/v1/orders/:id` | Read-only status + escrow. |\n| `place_order` | `POST /ncp/v1/orders` | **Real purchase.** Confirm-gated. |\n| `open_negotiation` | `POST /ncp/v1/negotiate/open` (`NcpClient.openNegotiation`) | **Real binding offer.** Confirm-gated. |\n| `book_stay` | `POST /ncp/v1/stays/:id/book` (preview via `…/quote`) | **Real booking, holds funds.** Confirm-gated. Requires `FEATURE_STAYS_ENABLED` on the server. |\n| `book_ride` | `POST /ncp/v1/rides` | Confirm-gated. Ride creation is a **Phase-2** server capability and may return \"not yet available\". |\n\n---\n\n## Never silent spend — the confirm gate\n\nThe four money-moving tools (`place_order`, `open_negotiation`, `book_stay`,\n`book_ride`) are **confirm-gated**:\n\n1. **First call (no `confirm`)** → the tool does a *read-only preview*: it\n   prices out the items / fetches a quote and returns a human-readable summary\n   (item, vendor, price, fees, total, and exactly what will happen). **Nothing\n   is bought or booked.**\n2. The MCP host shows that summary to the human.\n3. **Second call (`\"confirm\": true`)** → only now does the tool perform the real\n   action.\n\nCombined with the MCP host's own per-tool-call approval prompt, this guarantees\nan agent can never silently move a human's money.\n\n---\n\n## Development\n\n```bash\npnpm install                       # from the monorepo root\npnpm --filter @buychat/mcp build   # tsc → dist/\n\n# Smoke test (lists tools, then exits):\nnode packages/mcp-server/dist/index.js   # speaks MCP over stdio; Ctrl-C to stop\n```\n\nThe server writes the protocol to **stdout**; all logs go to **stderr**.\n\n## License\n\nMIT © BuyChat\n","readmeFilename":"README.md","_rev":"1-4130712968336caa0d8aca79ad2b8b5f"}