{"_id":"@biological-sovereignty-protocol/mcp","_rev":"2-4bf4ad5c7f173450668a52aae81f70da","name":"@biological-sovereignty-protocol/mcp","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@biological-sovereignty-protocol/mcp","version":"1.0.0","keywords":["bsp","mcp","biological-sovereignty","longevity","health-data","claude","model-context-protocol","arweave","biomarker","anthropic-mcp"],"author":{"name":"Ambrósio Institute"},"license":"Apache-2.0","_id":"@biological-sovereignty-protocol/mcp@1.0.0","maintainers":[{"name":"ambrosiocompany","email":"gestaoambrosio@outlook.com"}],"homepage":"https://biologicalsovereigntyprotocol.com/developers/sdk-reference","bugs":{"url":"https://github.com/Biological-Sovereignty-Protocol/bsp-mcp/issues"},"bin":{"bsp-mcp":"dist/index.js"},"dist":{"shasum":"1e899d3e84170ea495e09e8ab745ef489b8ae785","tarball":"https://registry.npmjs.org/@biological-sovereignty-protocol/mcp/-/mcp-1.0.0.tgz","fileCount":15,"integrity":"sha512-tHfrnPgUwy8FW0uaJaBQzQBImZpV9r01Jf4RjoNREEReq8awGsssWFBMlojRI0rUHAxmRIssLRNY9B0frS8UEg==","signatures":[{"sig":"MEYCIQDNNd9/e5zYfHYBqf3SteHDlCGr45Dv/90H+hJ4W7maaAIhAOBoLusEXwpC4I4Z3vKkJOMZDAXUc/7dzR1FRgZcC3lD","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":49407},"main":"dist/index.js","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"dad426c43a92667afce9931e05c09706fa9df8bc","scripts":{"dev":"ts-node src/index.ts","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"ambrosiocompany","email":"gestaoambrosio@outlook.com"},"repository":{"url":"git+https://github.com/Biological-Sovereignty-Protocol/bsp-mcp.git","type":"git"},"_npmVersion":"11.6.2","description":"Official BSP MCP Server — connects AI agents to the Biological Sovereignty Protocol with active consent enforcement","directories":{},"_nodeVersion":"24.13.0","dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","@biological-sovereignty-protocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.0","typescript":"^5.4.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_1.0.0_1775607040167_0.8900375791461625","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@biological-sovereignty-protocol/mcp","version":"1.0.1","description":"Official BSP MCP Server — connects AI agents to the Biological Sovereignty Protocol with active consent enforcement","main":"dist/index.js","bin":{"bsp-mcp":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"ts-node src/index.ts","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["bsp","mcp","biological-sovereignty","longevity","health-data","claude","model-context-protocol","arweave","biomarker","anthropic-mcp"],"author":{"name":"Ambrósio Institute"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/Biological-Sovereignty-Protocol/bsp-mcp.git"},"homepage":"https://biologicalsovereigntyprotocol.com/developers/sdk-reference","bugs":{"url":"https://github.com/Biological-Sovereignty-Protocol/bsp-mcp/issues"},"engines":{"node":">=18.0.0"},"dependencies":{"@biological-sovereignty-protocol/sdk":"^1.0.0","@modelcontextprotocol/sdk":"^1.0.0"},"devDependencies":{"@types/node":"^20.0.0","ts-node":"^10.9.0","typescript":"^5.4.0"},"gitHead":"b4d98f9b275c8a4a49c79ad12899a917342a2041","types":"./dist/index.d.ts","_id":"@biological-sovereignty-protocol/mcp@1.0.1","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-HSeSJEG4NvDySxLuqTIb8NlDCyMLo2RYz9JDl4WdPulwiY6tIJBEbYz+H95AV8sHxzqicIi6j2KL9KgfmMMF5A==","shasum":"4d75c82a71ab212d8f74f5eef00552712b8bb664","tarball":"https://registry.npmjs.org/@biological-sovereignty-protocol/mcp/-/mcp-1.0.1.tgz","fileCount":15,"unpackedSize":50037,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCX1dOSwViyAuoAVHqUaaFnLukTip8pF0HBvMuN/6UBbwIgEk11Bgt6pdzV9iJFC8bt6YuUK05XO2pIeVF1FeIBBlw="}]},"_npmUser":{"name":"ambrosiocompany","email":"gestaoambrosio@outlook.com"},"directories":{},"maintainers":[{"name":"ambrosiocompany","email":"gestaoambrosio@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_1.0.1_1775610418857_0.02887937224836712"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-08T00:10:40.074Z","modified":"2026-04-08T01:06:59.139Z","1.0.0":"2026-04-08T00:10:40.322Z","1.0.1":"2026-04-08T01:06:59.004Z"},"bugs":{"url":"https://github.com/Biological-Sovereignty-Protocol/bsp-mcp/issues"},"author":{"name":"Ambrósio Institute"},"license":"Apache-2.0","homepage":"https://biologicalsovereigntyprotocol.com/developers/sdk-reference","keywords":["bsp","mcp","biological-sovereignty","longevity","health-data","claude","model-context-protocol","arweave","biomarker","anthropic-mcp"],"repository":{"type":"git","url":"git+https://github.com/Biological-Sovereignty-Protocol/bsp-mcp.git"},"description":"Official BSP MCP Server — connects AI agents to the Biological Sovereignty Protocol with active consent enforcement","maintainers":[{"name":"ambrosiocompany","email":"gestaoambrosio@outlook.com"}],"readme":"![BSP MCP](https://img.shields.io/badge/MCP-compatible-6e40c9?style=flat-square) ![Version](https://img.shields.io/npm/v/bsp-mcp?style=flat-square&label=version) ![License](https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square) ![Node](https://img.shields.io/badge/node-%3E%3D18-green?style=flat-square)\n\n# bsp-mcp\n\n**Connect AI to health data — with verified consent**\n\n> Published by the [Ambrósio Institute](https://ambrosioinstitute.org) · [biologicalsovereigntyprotocol.com](https://biologicalsovereigntyprotocol.com)\n\n---\n\n## What it is\n\n`bsp-mcp` is the official Model Context Protocol server for the Biological Sovereignty Protocol. It lets any MCP-compatible AI assistant — Claude, GPT, or any other — read and interact with a user's BSP health records. But it never does so silently: every single data access is gated by a ConsentToken that the user explicitly issued, with cryptographic verification enforced on-chain.\n\nThe server implements the MCP tool interface over stdio, integrates with the `bsp-sdk` ExchangeClient, and treats consent as a hard runtime constraint — not a UI checkbox. If a valid token is not present, or if the requested intent falls outside what was authorized, the call is rejected before any data is touched.\n\n---\n\n## Why this matters\n\nIn 2026, AI health assistants are everywhere. The problem is that most of them access health data through institutional pipelines where the user is a bystander — data flows from EHR to platform to model, and the individual never sees the consent trail, let alone controls it.\n\nBSP-MCP inverts that. Every query your AI makes is gated by a ConsentToken you issued, scoped to exactly the categories and intents you authorized, with an expiry you set. The AI sees what you allowed — nothing more. When you revoke access, it stops immediately. The entire access history is permanently recorded on Arweave, auditable by anyone.\n\nThis is what sovereign health data looks like in practice.\n\n---\n\n## Available Tools\n\n| Tool | Consent Required | What it returns |\n|---|---|---|\n| `bsp_get_biorecords` | Yes — `READ_RECORDS` intent | Biological measurements in BSP format: values, units, reference ranges, collection timestamps. Filterable by category, biomarker codes, and date range. |\n| `bsp_get_beo_summary` | Yes — `READ_RECORDS` intent | Overview of the user's biological profile: categories present, record counts, last measurement dates, and data coverage level. |\n| `bsp_resolve_biomarker` | No — public taxonomy | Name, category, level, and clinical context for a BSP biomarker code. |\n| `bsp_list_categories` | No — public taxonomy | All 25 BSP taxonomy categories with level filters (CORE / STANDARD / EXTENDED / DEVICE). |\n| `bsp_check_consent` | No — reads session config | Active consent status: which BEO is connected, which intents are authorized, token ID, and expiry. Run this first. |\n| `bsp_lock_beo` | Yes — `BSP_PRIVATE_KEY` | Emergency lock — freezes the BEO immediately. No operations permitted while locked. |\n| `bsp_unlock_beo` | Yes — `BSP_PRIVATE_KEY` | Unlock a previously locked BEO. |\n| `bsp_destroy_beo` | Yes — `BSP_PRIVATE_KEY` + `confirm: true` | **IRREVERSIBLE** — Permanent erasure (LGPD/GDPR). Nullifies key, revokes all tokens, releases domain. |\n| `bsp_revoke_all_tokens` | Yes — `BSP_PRIVATE_KEY` | Emergency revoke ALL active ConsentTokens for a BEO. |\n\n---\n\n## Setup\n\n**1. Install**\n\n```bash\nnpx bsp-mcp\n```\n\n**2. Configure in Claude Desktop**\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"bsp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"bsp-mcp\"],\n      \"env\": {\n        \"BSP_BEO_DOMAIN\": \"yourname.bsp\",\n        \"BSP_CONSENT_TOKEN_ID\": \"tok_...\",\n        \"BSP_NETWORK\": \"mainnet\"\n      }\n    }\n  }\n}\n```\n\n**3. Issue a ConsentToken**\n\nBefore your AI can read any records, you need to authorize it from your BSP identity:\n\n```bash\nbsp consent grant \\\n  --beo yourname.bsp \\\n  --intent READ_RECORDS \\\n  --categories BSP-HM,BSP-GL,BSP-LA \\\n  --expires 2026-12-31 \\\n  --output tok_...\n```\n\nThen set that token ID as `BSP_CONSENT_TOKEN_ID` in the server env.\n\n**4. Verify the connection**\n\nStart a Claude session and ask:\n\n> \"Check my BSP consent status\"\n\nClaude will call `bsp_check_consent` and confirm which BEO is connected and what data it can access.\n\n---\n\n## Demo conversation\n\n```\nUser: Analyze my latest blood panel results\n\nClaude: Let me check your BSP consent first.\n\n  [bsp_check_consent]\n  → BEO: alice.bsp\n  → Token: tok_7f3a...c291\n  → Network: mainnet\n  → Intents: READ_RECORDS\n  → Authorized categories: BSP-HM (Hematology), BSP-GL (Genomics Light), BSP-LA (Lab – Advanced)\n  → Expires: 2026-12-31\n\n  Consent verified. Fetching your hematology records.\n\n  [bsp_get_biorecords]\n  → BEO: alice.bsp\n  → Category: BSP-HM\n  → Date range: last 90 days\n  → Records returned: 12\n\nBased on your latest blood panel (March 18, 2026):\n\n  Hemoglobin     14.2 g/dL   ✓  normal (ref: 12.0–16.0)\n  Hematocrit     42.1 %      ✓  normal (ref: 36–48)\n  WBC            7,200 /μL   ✓  normal (ref: 4,500–11,000)\n  Platelets      238,000 /μL ✓  normal (ref: 150,000–400,000)\n  MCV            88 fL       ✓  normal (ref: 80–100)\n  Ferritin       22 ng/mL    ⚠  low-normal (ref: 20–200; optimal longevity: >50)\n\nEverything is within clinical range. Ferritin at 22 ng/mL is technically normal,\nbut for longevity optimization the target is typically above 50. Worth discussing\niron supplementation or dietary adjustments with your provider.\n```\n\n---\n\n## Security model\n\n**How consent verification works**\n\nThe `ConsentGuard` runs before every data-access tool call. It checks that:\n\n1. A BEO domain is configured (`BSP_BEO_DOMAIN`)\n2. A ConsentToken is present (`BSP_CONSENT_TOKEN_ID`)\n3. The token's `intents` array includes the required intent for the requested operation\n4. The token has not expired\n\nWhen `bsp-sdk` is connected to the registry, step 3 and 4 are verified on-chain against the AccessControl contract. The token state on Arweave is the source of truth — not the local environment.\n\n**What happens when a token expires**\n\n```\n[bsp_get_biorecords]\n⛔ BSP Consent Error [TOKEN_EXPIRED]\n\nThe ConsentToken tok_7f3a...c291 expired on 2026-06-01.\nThe BEO holder must issue a new token to continue.\n→ https://biologicalsovereigntyprotocol.com/getting-started/quickstart\n```\n\nThe AI cannot proceed. No data is returned. No fallback path exists.\n\n**What happens when a token is revoked**\n\nRevocation is immediate. The AccessControl contract on Arweave marks the token as revoked, and the next tool call that hits the registry will receive a `TOKEN_REVOKED` error and halt. Mid-conversation revocation is handled gracefully — the AI acknowledges the revocation and stops accessing data.\n\n**Scope enforcement**\n\nTokens are scoped. A token with `READ_RECORDS` on `BSP-HM,BSP-GL` cannot be used to read `BSP-CV` (cardiovascular) data even if that category exists in the BEO. Category-level enforcement is delegated to the AccessControl contract.\n\n---\n\n## For developers\n\n**Adding a new tool**\n\nTools are registered in `src/index.ts`. Each tool follows this pattern:\n\n```typescript\n// 1. Define the tool in the tools[] array\n{\n  name: 'bsp_my_new_tool',\n  description: '...',\n  inputSchema: { type: 'object', properties: { ... } }\n}\n\n// 2. Add a case in the CallToolRequestSchema handler\ncase 'bsp_my_new_tool': {\n  // For consent-required tools:\n  const consentError = guard.check('REQUIRED_INTENT')\n  if (consentError) return consentError\n\n  // Your tool logic here\n  // Use bsp-sdk ExchangeClient to interact with the registry\n}\n```\n\n**Tool interface**\n\nEvery tool returns an `MCPResult`:\n\n```typescript\ntype MCPResult = {\n  content: Array<{ type: 'text'; text: string }>\n  isError?: boolean\n}\n```\n\n**Environment variables**\n\n| Variable | Required | Description |\n|---|---|---|\n| `BSP_BEO_DOMAIN` | Yes | The user's BSP identity domain (e.g. `alice.bsp`) |\n| `BSP_CONSENT_TOKEN_ID` | Yes for data access | Token ID issued by the BEO holder |\n| `BSP_RELAYER_URL` | No | Override registry endpoint (default: official relayer) |\n| `BSP_NETWORK` | No | `mainnet` or `testnet` (default: `mainnet`) |\n\n**Related packages**\n\n- [bsp-spec](https://github.com/Biological-Sovereignty-Protocol/bsp-spec) — full BSP specification\n- [bsp-sdk-typescript](https://github.com/Biological-Sovereignty-Protocol/bsp-sdk-typescript) — TypeScript SDK (`bsp-sdk`)\n- [bsp-id-web](https://github.com/ambrosio-institute/bsp-id-web) — web app to manage your BEO and issue tokens\n\n---\n\n## Changelog\n\n**v1.0.0** — Initial release\n- 9 tools: 5 read (`bsp_get_biorecords`, `bsp_get_beo_summary`, `bsp_resolve_biomarker`, `bsp_list_categories`, `bsp_check_consent`) + 4 write (`bsp_lock_beo`, `bsp_unlock_beo`, `bsp_destroy_beo`, `bsp_revoke_all_tokens`)\n- ConsentGuard with intent and BEO domain validation\n- Full BSP taxonomy: 25 categories, CORE/STANDARD/EXTENDED/DEVICE levels\n- stdio transport via `@modelcontextprotocol/sdk`\n\n---\n\n## License\n\nApache 2.0 — [Ambrósio Institute](https://ambrosioinstitute.org)\n","readmeFilename":"README.md"}