{"_id":"@blacksandscyber/mcp-server-bursar","_rev":"3-814204e4185cd7538ef45726c462490b","name":"@blacksandscyber/mcp-server-bursar","dist-tags":{"latest":"0.6.0"},"versions":{"0.5.0":{"name":"@blacksandscyber/mcp-server-bursar","version":"0.5.0","keywords":["mcp","blacksands","shield","zero-trust","security","ai-agent","claude","broker","mtls"],"author":{"name":"Blacksands Cyber, Inc."},"license":"MIT","_id":"@blacksandscyber/mcp-server-bursar@0.5.0","maintainers":[{"name":"b0bmarl3y","email":"npawl@blacksandsinc.com"}],"bin":{"shield-mcp":"dxt/scripts/setup.js","blacksands-shield-mcp":"dxt/scripts/setup.js","blacksands-shield-mcp-http":"build/http-transport.js"},"dist":{"shasum":"53bf2b39c7c1c3ac0c14dff41b37249b50d64a64","tarball":"https://registry.npmjs.org/@blacksandscyber/mcp-server-bursar/-/mcp-server-bursar-0.5.0.tgz","fileCount":68,"integrity":"sha512-XryPxLUYmwm/eP0y8Mcg6TR+Drnxqp+0aUrvnH9+rx/z84CiBLMeXKvgojROwzPRIaoDFkl/v/Ps4+jTMR+Etg==","signatures":[{"sig":"MEUCIBzaRH2+orRpRaHfg7bEPB2LHlBo6BzBhXc7CqUJnXEuAiEAgDxuANt0hwZHSALg5H0M4T+gzcgjZUXehks43gH3xNQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":512695},"main":"build/index.js","types":"./build/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"c4e7dfca9910cc31aaddf8af4da4b4edc37e6dce","scripts":{"dev":"tsc --watch","lint":"tsc --noEmit","test":"jest --forceExit --detectOpenHandles","build":"tsc","start":"node build/index.js","build:dxt":"bash scripts/build-dxt.sh","start:http":"node build/http-transport.js","prepublishOnly":"tsc"},"_npmUser":{"name":"b0bmarl3y","email":"npawl@blacksandsinc.com"},"_npmVersion":"10.8.2","description":"Blacksands Bursar MCP Server — zero-trust security operations for AI agents. Installable in Claude Code (`claude mcp add shield -- shield-mcp`) and Claude Desktop (drag-and-drop .dxt).","directories":{},"_nodeVersion":"20.20.2","dependencies":{"glob":"^10.3.0","ssh2":"^1.17.0","axios":"^1.7.0","js-yaml":"^4.1.1","@aws-sdk/client-ssm":"^3.1032.0","@modelcontextprotocol/sdk":"^1.8.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ajv":"^8.20.0","jest":"^29.7.0","adm-zip":"^0.5.17","ts-jest":"^29.1.0","typescript":"^5.3.0","@types/jest":"^29.5.0","@types/node":"^20.0.0","@types/ssh2":"^1.15.5","ajv-formats":"^3.0.1","@types/adm-zip":"^0.5.8","@types/js-yaml":"^4.0.9"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server-bursar_0.5.0_1782433965531_0.7770853301860157","host":"s3://npm-registry-packages-npm-production"}},"0.5.1":{"name":"@blacksandscyber/mcp-server-bursar","version":"0.5.1","keywords":["mcp","blacksands","shield","zero-trust","security","ai-agent","claude","broker","mtls"],"author":{"name":"Blacksands Cyber, Inc."},"license":"MIT","_id":"@blacksandscyber/mcp-server-bursar@0.5.1","maintainers":[{"name":"b0bmarl3y","email":"npawl@blacksandsinc.com"}],"bin":{"shield-mcp":"dxt/scripts/setup.js","blacksands-shield-mcp":"dxt/scripts/setup.js","blacksands-shield-mcp-http":"build/http-transport.js"},"dist":{"shasum":"0fdb144697e5f68e832be0b7998837c662846363","tarball":"https://registry.npmjs.org/@blacksandscyber/mcp-server-bursar/-/mcp-server-bursar-0.5.1.tgz","fileCount":88,"integrity":"sha512-j9ecFhiBvoih0nSko9GagRah2fUJSkgV41R1qq6HAmdYF99n3wQBtYygYVT4hjpVnfJT4Rx8KzZkf94eUuuQdw==","signatures":[{"sig":"MEUCIQCtN3j0W/gJky5KeKP2OIiU4mh+9Tah8zOpoejCv6UKngIgbOZclgTRBsCBAfKJQHOhw7X2NnBlDlfdDx9kJmedjt4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":705223},"main":"build/index.js","types":"./build/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"39fac0ef57c3fc7205b1bb36a99102554dda88fe","scripts":{"dev":"tsc --watch","lint":"tsc --noEmit","test":"jest --forceExit --detectOpenHandles","build":"tsc && node -e \"const fs=require('fs');fs.mkdirSync('build/presets',{recursive:true});for(const f of fs.readdirSync('presets'))if(f.endsWith('.zones.json'))fs.copyFileSync('presets/'+f,'build/presets/'+f)\"","start":"node build/index.js","build:dxt":"bash scripts/build-dxt.sh","start:http":"node build/http-transport.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"b0bmarl3y","email":"npawl@blacksandsinc.com"},"_npmVersion":"10.8.2","description":"Blacksands Bursar MCP Server — zero-trust security operations for AI agents. Installable in Claude Code (`claude mcp add shield -- shield-mcp`) and Claude Desktop (drag-and-drop .dxt).","directories":{},"_nodeVersion":"20.20.2","dependencies":{"glob":"^10.3.0","ssh2":"^1.17.0","axios":"^1.7.0","js-yaml":"^4.1.1","@aws-sdk/client-ssm":"^3.1032.0","@modelcontextprotocol/sdk":"^1.8.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ajv":"^8.20.0","jest":"^29.7.0","adm-zip":"^0.5.17","ts-jest":"^29.1.0","typescript":"^5.3.0","@types/jest":"^29.5.0","@types/node":"^20.0.0","@types/ssh2":"^1.15.5","ajv-formats":"^3.0.1","@types/adm-zip":"^0.5.8","@types/js-yaml":"^4.0.9"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server-bursar_0.5.1_1784924370727_0.628069460760722","host":"s3://npm-registry-packages-npm-production"}},"0.6.0":{"name":"@blacksandscyber/mcp-server-bursar","version":"0.6.0","description":"Blacksands Bursar MCP Server — zero-trust security operations for AI agents. Installable in Claude Code (`claude mcp add shield -- shield-mcp`) and Claude Desktop (drag-and-drop .dxt).","main":"build/index.js","bin":{"shield-mcp":"dxt/scripts/setup.js","blacksands-shield-mcp":"dxt/scripts/setup.js","blacksands-shield-mcp-http":"build/http-transport.js"},"scripts":{"build":"tsc && node -e \"const fs=require('fs');fs.mkdirSync('build/presets',{recursive:true});for(const f of fs.readdirSync('presets'))if(f.endsWith('.zones.json'))fs.copyFileSync('presets/'+f,'build/presets/'+f)\"","build:dxt":"bash scripts/build-dxt.sh","start":"node build/index.js","start:http":"node build/http-transport.js","dev":"tsc --watch","test":"jest --forceExit --detectOpenHandles","lint":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["mcp","blacksands","shield","zero-trust","security","ai-agent","claude","broker","mtls"],"author":{"name":"Blacksands Cyber, Inc."},"license":"MIT","publishConfig":{"access":"public"},"dependencies":{"@aws-sdk/client-ssm":"^3.1032.0","@modelcontextprotocol/sdk":"^1.8.0","axios":"^1.7.0","glob":"^10.3.0","js-yaml":"^4.1.1","ssh2":"^1.17.0"},"devDependencies":{"@types/adm-zip":"^0.5.8","@types/jest":"^29.5.0","@types/js-yaml":"^4.0.9","@types/node":"^20.0.0","@types/ssh2":"^1.15.5","adm-zip":"^0.5.17","ajv":"^8.20.0","ajv-formats":"^3.0.1","jest":"^29.7.0","ts-jest":"^29.1.0","typescript":"^5.3.0"},"engines":{"node":">=18.0.0"},"_id":"@blacksandscyber/mcp-server-bursar@0.6.0","gitHead":"c3803a91610f6c5f207ac41c9003792dc5ed25de","types":"./build/index.d.ts","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-2Qk9TY5AviWNx5iUyZperi3hhpV0SxoK6S/damNLYBPzbheRR2hL+Bp5v/apsP9T37fjLA97Q3avUNLiTID3Xw==","shasum":"62eaf09a5983357a5b42e9c0d8c0df361173ca43","tarball":"https://registry.npmjs.org/@blacksandscyber/mcp-server-bursar/-/mcp-server-bursar-0.6.0.tgz","fileCount":88,"unpackedSize":708749,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGRKq4HSCB7kJqD3uVqPRr8iHNzuRBgg7vmCTXnwfj8VAiEAndzxKS7iBSByUGtTYAemwkSbHXXAtguFZX3pX4GyAyw="}]},"_npmUser":{"name":"b0bmarl3y","email":"npawl@blacksandsinc.com"},"directories":{},"maintainers":[{"name":"b0bmarl3y","email":"npawl@blacksandsinc.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server-bursar_0.6.0_1785437232925_0.9762351665628868"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-26T00:32:45.439Z","modified":"2026-07-30T18:47:13.275Z","0.5.0":"2026-06-26T00:32:45.675Z","0.5.1":"2026-07-24T20:19:30.953Z","0.6.0":"2026-07-30T18:47:13.086Z"},"author":{"name":"Blacksands Cyber, Inc."},"license":"MIT","keywords":["mcp","blacksands","shield","zero-trust","security","ai-agent","claude","broker","mtls"],"description":"Blacksands Bursar MCP Server — zero-trust security operations for AI agents. Installable in Claude Code (`claude mcp add shield -- shield-mcp`) and Claude Desktop (drag-and-drop .dxt).","maintainers":[{"name":"b0bmarl3y","email":"npawl@blacksandsinc.com"}],"readme":"# @blacksandscyber/mcp-server-bursar\n\nZero-trust security operations for AI agents. **55 tools** for codebase analysis, application provisioning, mTLS certificate management, compliance reporting, and Receiver proxy lifecycle — exposed through the Model Context Protocol so Claude (or any MCP client) can drive Blacksands Bursar directly.\n\nTwo install paths, depending on which Claude surface you use:\n\n| Surface | Install | Effort |\n|---|---|---|\n| **Claude Code** | `claude mcp add bursar -- npx -y @blacksandscyber/mcp-server-bursar` | One command |\n| **Claude Desktop** | Drag-and-drop the signed `.dxt` bundle | One drag |\n\n**14 tools work without any Blacksands account.** Codebase scanning, framework detection, PII discovery, deployment guidance — installed and ready immediately. Sign up at [bursar.blacksandscyber.online](https://bursar.blacksandscyber.online) to unlock the remaining 41 tools (provisioning, compliance, Receiver management).\n\n## Learn more\n\n- [Bursar FAQ](../docs/shield-mcp/bursar-faq.md) — why the auth model works the way it does, per-tool gotchas, and troubleshooting.\n- [Training guide](../docs/shield-mcp/training-guide/index.html) — every tool, by category, with example calls/responses.\n- [Bursar AI Agents knowledge base](https://onboard.beta.blacksandscyber.online/knowledge-base/bursar-ai-agents) — the live customer-facing KB for account, plan, and billing questions (this README covers tool-level detail, not account setup).\n\n---\n\n## Claude Code — one-line install\n\nThe fastest path. Works in any directory — Claude Code launches the MCP server when needed.\n\n```bash\n# Local-only mode — 14 [FREE] tools work immediately, no account needed\nclaude mcp add bursar -- npx -y @blacksandscyber/mcp-server-bursar\n\n# Verify\nclaude mcp list\n# bursar: npx -y @blacksandscyber/mcp-server-bursar - ✓ Connected\n```\n\nThen, in any Claude Code session:\n\n```\n> Scan my project at ~/some-app for security risks\n[Claude calls bursar_scan_codebase, returns the security manifest]\n\n> What's the Blacksands deployment architecture?\n[Claude calls bursar_guide_deployment, returns the authoritative overview]\n```\n\n### Bring your own credentials (full Bursar API access)\n\nTo unlock all 55 tools, pass your existing cert bundle (issued through Overwatch / SysAdmin / a setup token):\n\n```bash\nclaude mcp add bursar \\\n  --env SHIELD_AUTHORIZER_URL=https://mauth-beta.blacksandscyber.online \\\n  --env SHIELD_CLIENT_CERT=$HOME/.blacksands/mcp-certs/test-mcp9.crt \\\n  --env SHIELD_CLIENT_KEY=$HOME/.blacksands/mcp-certs/test-mcp9.key \\\n  --env SHIELD_AUTH_PASSWORD=$(cat $HOME/.blacksands/mcp-certs/.auth-password) \\\n  --env SHIELD_ORG_ID=blacksands \\\n  -- npx -y @blacksandscyber/mcp-server-bursar\n```\n\nOr, for a one-time bootstrap with a setup token from your Blacksands admin:\n\n```bash\nclaude mcp add bursar \\\n  --env SHIELD_SETUP_TOKEN=bss_xxxxxxxxxxxx \\\n  -- npx -y @blacksandscyber/mcp-server-bursar\n```\n\nThe MCP server redeems the token on first launch, persists the cert bundle to `~/.blacksands/mcp-certs/`, and uses it for every subsequent run.\n\n---\n\n## Claude Desktop — drag-and-drop the .dxt\n\n1. Build (or download) `blacksands-bursar-x.y.z.dxt`:\n   ```bash\n   cd mcp-server-blacksands-bursar\n   MANIFEST=manifest-v2.json npm run build:dxt\n   # outputs build/blacksands-bursar-x.y.z.dxt\n   ```\n2. Drag the `.dxt` onto the Claude Desktop app icon.\n3. Confirm install. Send a chat message — the MCP server starts on first tool call.\n\nFor the non-coder onboarding flow (admin issues a setup token, user clicks the install email), see [`docs/shield-mcp/MCP-ONBOARDING.md`](../docs/shield-mcp/MCP-ONBOARDING.md).\n\n---\n\n## What you get\n\n### 14 [FREE] tools — no account needed\n\nRun on any local project. No network calls except for `bursar_guide_deployment`'s overview text (which is bundled).\n\n| Tool | What it does |\n|---|---|\n| `bursar_scan_codebase` | Composite scan — framework, endpoints, PII, services, datastores, manifest |\n| `bursar_scan_environment` | Read-only local host/container topology scan (macOS), for the visualization app |\n| `bursar_detect_framework` | Express, Flask, Rails, Next.js, Django, etc. |\n| `bursar_scan_endpoints` | Extract HTTP/API routes with method + auth detection |\n| `bursar_flag_pii_candidates` | SSN, credit card, health data, DOB; produces compliance hints |\n| `bursar_detect_external_services` | Stripe, OpenAI, AWS, Firebase, Twilio, etc. |\n| `bursar_detect_data_stores` | PostgreSQL, MongoDB, Redis, ORMs |\n| `bursar_generate_manifest` | Assemble detection results into a Security Manifest JSON |\n| `bursar_report_activity` | Cosmetic activity event to the local Container-Manager visualization (no state change) |\n| `bursar_show_topology` | Open/link the local Container-Manager topology visualization |\n| `bursar_get_protection_requirements` | Plain-English checklist of what's needed to protect this app |\n| `bursar_guide_deployment` | Authoritative deployment walkthrough — DigitalOcean Droplet, local-docker dev, etc. |\n| `broker_get_protocol_walkthrough` | Authoritative broker auth-chain protocol description + Node/Python/curl examples |\n| `broker_get_my_identity` | Returns the calling MCP cert's identity: CN, RBAC role, org id, client name, tier |\n\n### 41 tools requiring a Blacksands account\n\nProvisioning (`bursar_create_org`, `bursar_create_app`, `bursar_provision_app`, `bursar_install_agent_remotely`), compliance (`bursar_compliance_report`, `bursar_compliance_controls`), certs (`bursar_list_certs`, `bursar_revoke_cert`, `bursar_rotate_cert`), Receiver lifecycle (`receiver_initialize`, `receiver_activate`, `receiver_onboard_service`, `receiver_health`), sessions (`bursar_list_sessions`, `bursar_revoke_session`), and emergency controls (`bursar_emergency_lockdown`, `bursar_lift_lockdown`).\n\nCalling any of these in local-only mode returns a friendly setup-token prompt instead of a stack trace.\n\n---\n\n## Configuration\n\nAll env vars are optional except where noted. Sensible defaults are baked in so the MCP server starts in local-only mode with zero configuration.\n\n| Var | Default | Required for | Description |\n|---|---|---|---|\n| `MCP_TRANSPORT` | `stdio` | — | Set to `local-only` to skip all auth and run only the 14 [FREE] tools |\n| `SHIELD_AUTHORIZER_URL` | `https://mauth-beta.blacksandscyber.online` | broker mode | Where the MCP client authenticates to Bursar |\n| `SHIELD_SETUP_URL` | `https://onboard.beta.blacksandscyber.online` | token bootstrap | Where setup tokens are redeemed |\n| `SHIELD_SETUP_TOKEN` | (none) | first-time bootstrap | One-time `bss_…` token from a Blacksands admin |\n| `SHIELD_CLIENT_CERT` | (none) | broker mode | Path to mTLS client cert PEM file |\n| `SHIELD_CLIENT_KEY` | (none) | broker mode | Path to mTLS client key PEM file |\n| `SHIELD_AUTH_PASSWORD` | (none) | broker mode | Cert bundle's auth password |\n| `SHIELD_ORG_ID` | (none) | broker mode | Your organization id |\n| `SHIELD_CA_CERT` | bundled | optional | Path to Blacksands CA cert (override the bundled one) |\n| `LOG_LEVEL` | `info` | — | `debug`, `info`, `warn`, `error` |\n\nPersisted state lives in `~/.blacksands/mcp-certs/`:\n- `<client-name>.crt`, `<client-name>.key` — your mTLS bundle\n- `.auth-password`, `.client-name`, `.org-id`, `.last-token-prefix` — bookkeeping\n- `blacksands-ca.crt` — the Blacksands CA chain\n\nTo rotate credentials: `rm -rf ~/.blacksands/mcp-certs/`, then start the MCP server with a fresh `SHIELD_SETUP_TOKEN`.\n\n---\n\n## Accessing protected services\n\nOnce your agent has a valid mTLS cert (issued by Blacksands), reaching a protected service is **NOT** a single mTLS call. The auth chain is **bisected**: agent does mTLS to the **Authorizer** (which returns a list of services it's allowed to reach), then a SECOND independently-verified mTLS handshake to the **Receiver** (a public-IP edge proxy that forwards to the actual backend service).\n\n**For LLM-generated client code:** ask Claude to call **`broker_get_protocol_walkthrough`** before generating anything. That tool returns the authoritative protocol description plus copy-paste examples in Node.js, Python, and curl. Don't let Claude improvise the auth chain from training-data assumptions about mTLS — Blacksands is unusual: cert at TWO independent stages, backend service URL never reachable directly.\n\n```\n                  INTERNET\n                     │\n                     │  443 (mTLS, mandatory)\n                     ▼\n         ┌────────────────────┐\n         │     Authorizer     │  ← step 1: agent mTLS handshake\n         │  (mauth-…)         │  ← step 2: returns service-list with Receiver URLs\n         └────────────────────┘\n                     │\n                     │  agent picks service, builds URL with sessionToken\n                     ▼\n         ┌────────────────────┐\n         │     Receiver       │  ← step 4: SECOND mTLS handshake (same cert,\n         │  (public IP edge)  │            re-verified independently)\n         └─────────┬──────────┘\n                   │ private network\n                   ▼\n              backend service\n              (never reachable directly)\n```\n\nThe MCP server's `broker_get_protocol_walkthrough` tool is the canonical reference — fetched lazily when an LLM needs it. Same content is also surfaced as the `blacksands://broker-protocol` MCP resource for clients (like Claude Desktop) that prime context at session start.\n\nA minimal Node.js sketch:\n\n```js\nconst agent = new https.Agent({ cert, key, ca });\n\n// STEP 1+2: mTLS to Authorizer, get service URL + token\nconst auth = await axios.post(\n  'https://mauth-beta.blacksandscyber.online/api/agent/auth',\n  { password, serviceId: 'bursar-api' },\n  { httpsAgent: agent }\n);\nconst receiverUrl = auth.data.service.serviceUrl;  // points at the Receiver, not the service\nconst [base, qs] = receiverUrl.split('?');\nconst token = new URLSearchParams(qs).get('token');\n\n// STEP 3+4+5+6: SAME agent reused for the second mTLS handshake\nconst api = axios.create({\n  baseURL: `${base}/v1`,\n  httpsAgent: agent,        // same cert presented again, Receiver re-verifies independently\n  params: { token },\n});\nconst orgs = await api.get('/orgs');\n```\n\nFull Node.js, Python, and curl examples — plus the anti-patterns to avoid — are in the tool's output.\n\n---\n\n## Verifying the install\n\n```bash\n# Should show \"bursar: ... ✓ Connected\"\nclaude mcp list\n\n# Quickest check — call a [FREE] tool that doesn't need Bursar API\nclaude --print \"What is the Blacksands deployment architecture? Use bursar_guide_deployment.\"\n```\n\nThe MCP server logs to stderr (stdout is reserved for the MCP wire protocol). On macOS look in `~/Library/Logs/Claude/mcp-server-Bursar.log` (Claude Desktop) or run with `claude --mcp-debug` (Claude Code).\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/b0bmarl3y/Blacksands_2_0.git\ncd Blacksands_2_0/mcp-server-blacksands-bursar\nnpm install\nnpm run lint && npm test          # 137 tests, ~4s\nnpm run build                     # tsc → build/\nnode dxt/scripts/setup.js         # boot the server directly\n```\n\nTest harness layout:\n\n| Tier | Location | What it covers | Cadence |\n|---|---|---|---|\n| 1 | `tests/manifest.test.ts`, `tests/dxt-package.test.ts`, `tests/bursar/deploy/*`, `tests/config.test.ts`, `tests/server-tags.test.ts` | DXT manifest spec, content invariants on tool output, mode dispatch, [FREE] tag discipline | Every commit |\n| 2 | `tests/harness/*` | MCP wire-protocol harness — spawns the compiled server and exercises tools/list + tools/call against a fixture project | Every PR |\n| 3 | `tests/integration/live-broker.test.ts` (gated) | Live broker chain canary against the real Bursar API | Release / on-demand (`RUN_LIVE_INTEGRATION=1`) |\n| 4 | (manual checklist) | Drag-install validation + LLM behavior + destructive-tool exercise | Release prep |\n\n---\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n\nFor commercial support, custom integrations, or enterprise deployments (cryptographic remote attestation, HSM-backed cert storage, on-prem control plane), contact [support@blacksands.io](mailto:support@blacksands.io).\n","readmeFilename":"README.md"}