{"_id":"@borgresearch/odin-mcp","_rev":"3-57ed4873e97cc009723bab88539d2cab","name":"@borgresearch/odin-mcp","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@borgresearch/odin-mcp","version":"0.1.0","keywords":["mcp","model-context-protocol","odin","security"],"author":{"name":"Borg Research"},"license":"MIT","_id":"@borgresearch/odin-mcp@0.1.0","maintainers":[{"name":"sjalu","email":"hans@borgresearch.io"}],"homepage":"https://github.com/BorgDevelopment/borg-platform/tree/develop/frontend/packages/odin-mcp","bugs":{"url":"https://github.com/BorgDevelopment/borg-platform/issues"},"bin":{"odin-mcp":"dist/index.js"},"dist":{"shasum":"06d0036e86f7593b2af63611e47e1b5fe615abb6","tarball":"https://registry.npmjs.org/@borgresearch/odin-mcp/-/odin-mcp-0.1.0.tgz","fileCount":6,"integrity":"sha512-/rT92YL6zrBFnJe8pA67Zk7sLMMbgZ8EGqTPcGfJm2YEoWJuqJCr7qxkKE7jGqa8aN2yiaOwBS90qf72AHaF8g==","signatures":[{"sig":"MEYCIQCg/jhnKSZ/p+W0gNyBHpVVoowlSWdbYDdHL0cNdPJ9bwIhAIWzl4RpstX2+1+dNtb15Tyu8Q1mdL1AuVWuxCYdVVMQ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":64924},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=22.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"1e1f0aa99e9f12e8dc019900c030c1fb2ed2d36b","scripts":{"dev":"tsup --watch","lint":"biome check .","test":"vitest run","build":"tsup","format":"biome format --write .","inspect":"mcp-inspector node dist/index.js","test:run":"vitest run","typecheck":"tsc --noEmit","inspect:dev":"pnpm build && pnpm inspect"},"_npmUser":{"name":"sjalu","email":"hans@borgresearch.io"},"repository":{"url":"git+https://github.com/BorgDevelopment/borg-platform.git","type":"git","directory":"frontend/packages/odin-mcp"},"_npmVersion":"10.9.7","description":"MCP server for the Odin security API","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^4.3.6","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","vitest":"^4.1.0","typescript":"^5.9.3","@types/node":"^22.19.8","@biomejs/biome":"2.3.14","@modelcontextprotocol/inspector":"^0.21.2"},"_npmOperationalInternal":{"tmp":"tmp/odin-mcp_0.1.0_1777292680372_0.4803669178537606","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@borgresearch/odin-mcp","version":"0.2.0","description":"MCP server for the Odin security API","keywords":["mcp","model-context-protocol","odin","security"],"homepage":"https://github.com/BorgDevelopment/borg-platform/tree/develop/frontend/packages/odin-mcp","bugs":{"url":"https://github.com/BorgDevelopment/borg-platform/issues"},"repository":{"type":"git","url":"git+https://github.com/BorgDevelopment/borg-platform.git","directory":"frontend/packages/odin-mcp"},"license":"MIT","author":{"name":"Borg Research"},"type":"module","bin":{"odin-mcp":"dist/index.js"},"main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"engines":{"node":">=24.0.0"},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","test":"vitest run","test:run":"vitest run","lint":"biome check .","format":"biome format --write .","inspect":"mcp-inspector node dist/index.js","inspect:dev":"pnpm build && pnpm inspect"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^4.3.6"},"devDependencies":{"@biomejs/biome":"2.3.14","@modelcontextprotocol/inspector":"^0.21.2","@types/node":"^24.10.1","tsup":"^8.3.5","typescript":"^5.9.3","vitest":"^4.1.0"},"gitHead":"4d0f8dd3ba8891e5506f596236b9f12bde3566fb","_id":"@borgresearch/odin-mcp@0.2.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-gsGaLReWL9+hy/zaCADnuEo+SWBd54sVJh8Kv7lqaGP9bzCawehB4/EGqZz/wMQUrkRBKNKvxlBY+Qq02ChHzw==","shasum":"f5c41ec225bb62f5164569b07dd06414bcd13a35","tarball":"https://registry.npmjs.org/@borgresearch/odin-mcp/-/odin-mcp-0.2.0.tgz","fileCount":6,"unpackedSize":98331,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCaSf+usNImjjF6k2NOsTHmAHcSdqGZ5Dk4orT6NGi87AIgDpPzZgHC73C7Bl65BfWDVs9aj0sgM/kQMVLIpGAwjK4="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:04ad200a-b2ea-4c3a-883b-3e630313b633"}},"directories":{},"maintainers":[{"name":"whitehatcypher","email":"richard@borgresearch.io"},{"name":"sjalu","email":"hans@borgresearch.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/odin-mcp_0.2.0_1786186043733_0.23959304272733095"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-27T12:24:40.300Z","modified":"2026-08-08T10:47:24.106Z","0.1.0":"2026-04-27T12:24:40.537Z","0.2.0":"2026-08-08T10:47:23.882Z"},"bugs":{"url":"https://github.com/BorgDevelopment/borg-platform/issues"},"author":{"name":"Borg Research"},"license":"MIT","homepage":"https://github.com/BorgDevelopment/borg-platform/tree/develop/frontend/packages/odin-mcp","keywords":["mcp","model-context-protocol","odin","security"],"repository":{"type":"git","url":"git+https://github.com/BorgDevelopment/borg-platform.git","directory":"frontend/packages/odin-mcp"},"description":"MCP server for the Odin security API","maintainers":[{"name":"whitehatcypher","email":"richard@borgresearch.io"},{"name":"sjalu","email":"hans@borgresearch.io"}],"readme":"# @borgresearch/odin-mcp\n\n[Model Context Protocol](https://modelcontextprotocol.io) server for the [Odin](https://odin.borghq.io) security platform by Borg. It gives coding agents organisation-scoped finding context and a safe GitHub-first remediation loop.\n\nThe MCP can inspect a finding such as `ODI-12`, show the remediation and suggested branch, link an existing accessible GitHub pull request, and report automatic retest history. It never creates commits, pushes branches, or creates pull requests.\n\n## Prerequisites\n\n- Node.js 24 or newer.\n- An Odin account with at least one organisation.\n- An Odin API key. **Read only** is enough for discovery, remediation context, and retest reads. **Read & Write** is required for status changes and linking an existing pull request.\n\n## Quick start\n\n1. Sign in to <https://odin.borghq.io>, open **Management > API Keys**, and create a key. The dialog defaults to **Read & Write** for the remediation workflow; choose **Read only** when the agent should only inspect data.\n2. Copy the full key — it is shown once.\n3. Add the server to your client:\n\n```sh\nODIN_API_KEY=odin_... npx @borgresearch/odin-mcp\n```\n\nYou can also install globally:\n\n```sh\nnpm install -g @borgresearch/odin-mcp\nODIN_API_KEY=odin_... odin-mcp\n```\n\nRestart your MCP client after changing its configuration. Nine tools should be available after startup.\n\n## Configuration\n\n| Variable | Required | Notes |\n|----------|----------|-------|\n| `ODIN_API_KEY` | yes | An organisation-scoped key with `read`; `write` is required for mutations. |\n| `ODIN_BASE_URL` | no | Odin API base URL. Defaults to `https://odin.borghq.io`. |\n\nEach call sends `Authorization: Bearer ${ODIN_API_KEY}`. Keys belong to one organisation. If you belong to multiple organisations, create one key per organisation and run a separate MCP server entry for each.\n\n## Tools\n\nAll tools accept one JSON object and return both a Markdown summary and a structured payload.\n\n| Name | Permission | Description |\n|------|------------|-------------|\n| `list_findings` | Read | List findings with pagination, severity, repository, current status, and title/identifier search. |\n| `get_finding` | Read | Get bounded remediation context, revision content, suggested branch, linked PRs, workflow readiness, and latest retest state. |\n| `update_finding_status` | Read & Write | Move a finding to `MITIGATING`, `OPEN_FOR_RETEST`, or `ACKNOWLEDGED`. Cookie-authenticated callers also need member role. |\n| `link_finding_pull_request` | Read & Write | Link an existing accessible GitHub PR. It does not create, modify, merge, or push a PR. |\n| `get_finding_retests` | Read | Read retest history; it never triggers a retest or spends credits. |\n| `list_pentests` | Read | List pentests for the organisation. |\n| `get_pentest` | Read | Get a pentest's status, schedule, and scope. |\n| `list_assets` | Read | List attack-surface assets with filters and pagination. |\n| `get_asset` | Read | Get an asset and the findings that reference it. |\n\n### Finding references\n\nFinding references are organisation-local. Prefer a human identifier such as `ODI-12`; an internal `findingId` is retained for chaining tool calls. Odin looks up the numeric suffix only within the organisation belonging to the API key and returns the canonical stored identifier. It never searches across organisations or reveals a cross-organisation match through an error.\n\n### `list_findings`\n\nOptional parameters include `pentestId`, `assetId`, `repository`, `severity` (`CRITICAL` | `HIGH` | `MEDIUM` | `LOW` | `INFORMATIONAL`), `status` (`REPORTED` | `ACKNOWLEDGED` | `MITIGATING` | `OPEN_FOR_RETEST` | `NEEDS_REVISION` | `FIXED_AND_RETESTED`), `search`, `sortBy` (`severity` | `createdAt`), `sortOrder`, `limit` (1–200, default 50), and `offset`.\n\n### `get_finding`\n\nProvide `identifier` or `findingId` (at least one is required). The response includes the current status and severity, revision summary/description/impact/details/remediation, affected assets, code reference where available, repository, linked GitHub PR metadata, `suggestedBranch`, retest state, and workflow blockers.\n\nExample prompt:\n\n> Explain `ODI-12`, show me the suggested branch, and tell me what must be ready before I open a PR.\n\n### GitHub remediation loop\n\n1. Ask `get_finding` about the human identifier.\n2. Create the returned branch, make and test the fix, commit it, push it, and open the GitHub PR yourself in Cursor or your normal development environment.\n3. Explicitly ask Odin to link that existing PR with `link_finding_pull_request` and its URL. The operation is idempotent and verifies that the organisation's GitHub App installation can access the repository.\n4. When the linked PR merges, automatic webhook processing may queue a retest. Use `get_finding_retests` to read `QUEUED`, `RUNNING`, `COMPLETED`, `SKIPPED`, or `FAILED` entries and their sanitised verdicts.\n\nOdin does not infer permission from a matching PR. Ask before linking a PR or changing status. The MCP does not create commits, push branches, create PRs, merge PRs, or manually trigger paid retests.\n\n### `update_finding_status`\n\nProvide `identifier` or `findingId` and one of:\n\n| Status | Use it when |\n|--------|-------------|\n| `MITIGATING` | You have started work on the fix. |\n| `OPEN_FOR_RETEST` | The fix is ready for verification. |\n| `ACKNOWLEDGED` | You accept the risk for now. |\n\nA Read-only key receives an actionable 403. Create a new Read & Write key for mutations; existing key permissions are not silently upgraded. `NEEDS_REVISION` and `FIXED_AND_RETESTED` are controlled by Borg's retest process.\n\n### `link_finding_pull_request`\n\nProvide `identifier` or `findingId` and an existing GitHub pull request `url`. The GitHub integration must be active and able to access the repository. The tool returns the canonical finding reference, verified PR metadata, resulting status, and workflow readiness. It does not modify GitHub.\n\n### `get_finding_retests`\n\nProvide `identifier` or `findingId`. The tool is read-only and distinguishes no history from a history containing queued/running, completed, skipped, or failed runs. It does not call the manual retest endpoint and never spends credits.\n\n### Other tools\n\n`list_pentests` takes no parameters and `get_pentest` requires `pentestId`. `list_assets` and `get_asset` retain their existing type, source, status, search, sorting, and pagination parameters.\n\n## Use with Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"odin\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@borgresearch/odin-mcp\"],\n      \"env\": {\n        \"ODIN_API_KEY\": \"odin_...\"\n      }\n    }\n  }\n}\n```\n\n## Use with Claude Code\n\n```sh\nclaude mcp add --transport stdio --env ODIN_API_KEY=odin_... odin -- npx -y @borgresearch/odin-mcp\n```\n\n## Use with Codex\n\nAdd to `~/.codex/config.toml`, then restart Codex:\n\n```toml\n[mcp_servers.odin]\ncommand = \"npx\"\nargs = [\"-y\", \"@borgresearch/odin-mcp\"]\nenv = { ODIN_API_KEY = \"odin_...\" }\n```\n\n## Use with Cursor\n\nOpen **Settings > MCP**, or add this to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"odin\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@borgresearch/odin-mcp\"],\n      \"env\": {\n        \"ODIN_API_KEY\": \"odin_...\"\n      }\n    }\n  }\n}\n```\n\n## Use with Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"odin\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@borgresearch/odin-mcp\"],\n      \"env\": {\n        \"ODIN_API_KEY\": \"odin_...\"\n      }\n    }\n  }\n}\n```\n\n## Use with VS Code (GitHub Copilot)\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"odin\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@borgresearch/odin-mcp\"],\n      \"env\": {\n        \"ODIN_API_KEY\": \"odin_...\"\n      }\n    }\n  }\n}\n```\n\n## Use with Cline\n\nOpen **Settings > MCP Servers > Edit MCP Settings** and add the same `mcpServers.odin` JSON shape shown for Cursor. Pass `ODIN_API_KEY` in the server environment and restart the client after editing its MCP configuration.\n\n## Troubleshooting\n\n**`ODIN_API_KEY is not set or invalid`** — check the key under **Management > API Keys**, confirm the client config sets `env.ODIN_API_KEY`, and restart the client.\n\n**`API key does not have write permission`** — the agent attempted a status change or PR link with a Read-only key. Create a new key with **Read & Write** permissions.\n\n**`Finding not found`** — check the `ODI-12` reference and the organisation associated with the key. Keys and human identifiers are organisation-scoped by design.\n\n**Retest history is unavailable** — the organisation's retest automation capability is gated or not configured. This does not enable manual retests; check the GitHub and automatic-retest settings.\n\n**The server starts but no tools appear** — most clients require a full restart after changing configuration. Confirm Node.js 24 or newer is on the client's `PATH` and inspect its MCP logs.\n\n## Development\n\n```sh\npnpm test:run\npnpm typecheck\npnpm lint\npnpm build\n```\n\n## License\n\nUNLICENSED. This package is published for use with the Odin platform; redistribution is not permitted.\n","readmeFilename":"README.md"}