{"_id":"@constellation-governance/mcp-server","_rev":"2-170b3ac2a6e284d875b06b598d910181","name":"@constellation-governance/mcp-server","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@constellation-governance/mcp-server","version":"0.1.0","keywords":["mcp","governance","ai-safety","constraints","model-context-protocol","claude","institutional-governance"],"license":"MIT","_id":"@constellation-governance/mcp-server@0.1.0","maintainers":[{"name":"rghadmaian","email":"roshan@ghadamian.com"}],"homepage":"https://github.com/constellation-gov/mcp-server#readme","bugs":{"url":"https://github.com/constellation-gov/mcp-server/issues"},"bin":{"constellation-mcp":"dist/index.js"},"dist":{"shasum":"f1f88114f96c140426f63d2061a049cc658c9933","tarball":"https://registry.npmjs.org/@constellation-governance/mcp-server/-/mcp-server-0.1.0.tgz","fileCount":58,"integrity":"sha512-iX7BgrroEusw4402LV1rnBw8sXTzSHFb2eg7bZvSo4AuDw7RVRf4yZU5x6KRoP2oBl/TtWb4vodoZYjCss0pxQ==","signatures":[{"sig":"MEQCIEfHpAXSaV1vAJqAmWfiiJhcflhsIhjFP8iXvIH8XhLlAiAMFHs5x0HesbrK94bEDNH/FYO/Mx9X2RVYtW6OF5Dbrg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":152072},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"9ede78e6d15b4b1f1ebe100691fa52e1af992f65","scripts":{"dev":"npx tsx src/index.ts","build":"tsc","start":"node dist/index.js","type-check":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"rghadmaian","email":"roshan@ghadamian.com"},"repository":{"url":"git+https://github.com/constellation-gov/mcp-server.git","type":"git"},"_npmVersion":"11.6.0","description":"Constellation MCP server — institutional governance for AI agents. Checks constraints before AI takes action.","directories":{},"_nodeVersion":"24.9.0","dependencies":{"zod":"^4.1.11","@modelcontextprotocol/sdk":"^1.26.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4","typescript":"^5","@types/node":"^22"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_0.1.0_1770626376540_0.40880192912154056","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-02-09T08:39:36.424Z","modified":"2026-02-09T23:17:52.870Z","0.1.0":"2026-02-09T08:39:36.681Z"},"bugs":{"url":"https://github.com/constellation-gov/mcp-server/issues"},"license":"MIT","homepage":"https://github.com/constellation-gov/mcp-server#readme","keywords":["mcp","governance","ai-safety","constraints","model-context-protocol","claude","institutional-governance"],"repository":{"url":"git+https://github.com/constellation-gov/mcp-server.git","type":"git"},"description":"Constellation MCP server — institutional governance for AI agents. Checks constraints before AI takes action.","maintainers":[{"email":"roshan@ghadamian.com","name":"rghadmaian"},{"email":"roshan@constellation.foundation","name":"rghadamian"}],"readme":"# @elevate/constellation-mcp\n\nMCP server for institutional governance — \"AI that checks before it acts.\"\n\nConstellation surfaces constraints, traces decisions, and records institutional memory. It never blocks actions; it **informs** them.\n\n## Tools\n\n### `check` — \"Can I do X?\"\n\nEvaluates an intended action against institutional constraints.\n\n```json\n{\n  \"action\": \"spend $15,000 on new servers\",\n  \"domain\": \"finance\",\n  \"context\": { \"amount\": 15000 }\n}\n```\n\nReturns: whether the action is allowed, what constraints apply, what approvals are needed, and human-readable advice.\n\n### `boundary` — \"What are my limits?\"\n\nReturns all active constraints, grouped by type.\n\n```json\n{\n  \"domain\": \"communications\",\n  \"includeRationale\": true\n}\n```\n\nReturns: constraint list with optional rationale and authorship (Symmetry Principle — you can see the rules that govern you and why they exist).\n\n### `record` — \"This happened\"\n\nRecords an action that was taken, creating an institutional trace.\n\n```json\n{\n  \"action\": \"published quarterly results blog post\",\n  \"domain\": \"communications\",\n  \"outcome\": \"published successfully after board approval\"\n}\n```\n\nSupports overrides with required justification (Override Principle):\n\n```json\n{\n  \"action\": \"emergency press release about data breach\",\n  \"domain\": \"communications\",\n  \"outcome\": \"published within 30 minutes of discovery\",\n  \"overrideConstraintId\": \"timing-comms-001\",\n  \"overrideJustification\": \"Legal obligation to disclose within 72 hours. Board chair verbally approved at 2:15am.\"\n}\n```\n\n## Constitutional Principles\n\n- **Institutional Memory**: Every tool call creates a trace\n- **Symmetry**: Constraints include authorship and rationale — actors see the rules that govern them\n- **Override Principle**: Any constraint can be overridden, but overrides must be explicit, attributable, and evidentiary\n- **Human Judgment**: Tools never block — they surface constraints and advise\n- **Non-Surveillance**: Traces exist for memory, not for ranking individuals\n\n## Setup\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"constellation\": {\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"/absolute/path/to/packages/constellation-mcp/src/index.ts\"]\n    }\n  }\n}\n```\n\nThen restart Claude Desktop. The five tools (`check`, `boundary`, `record`, `escalate`, `preview`) will appear in the tools menu.\n\n### Claude Code\n\nAdd to `.claude/settings.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"constellation\": {\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"/absolute/path/to/packages/constellation-mcp/src/index.ts\"]\n    }\n  }\n}\n```\n\nClaude Code will pick up the MCP server automatically. You can verify with `/mcp` in the CLI.\n\n### Database Persistence (Optional)\n\nTo persist traces to the Constellation database, set these environment variables in your MCP server config:\n\n```json\n{\n  \"mcpServers\": {\n    \"constellation\": {\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"/absolute/path/to/packages/constellation-mcp/src/index.ts\"],\n      \"env\": {\n        \"CONSTELLATION_API_URL\": \"http://localhost:3000\",\n        \"CONSTELLATION_API_KEY\": \"csk_your_api_key_here\",\n        \"CONSTELLATION_INSTITUTION_ID\": \"your_institution_id\",\n        \"CONSTELLATION_ACTOR_ID\": \"your_clerk_user_id\"\n      }\n    }\n  }\n}\n```\n\nWithout these, traces are stored in-memory only (lost on restart). With them, every check/record/escalate is persisted and visible in the Governance > Traces page.\n\n### Development\n\n```bash\n# Install dependencies (from monorepo root)\npnpm install\n\n# Type check\npnpm --filter @elevate/constellation-mcp type-check\n\n# Run server (stdio — will wait for input)\npnpm --filter @elevate/constellation-mcp start\n```\n\n## Architecture\n\n```\nsrc/\n├── index.ts              # MCP server entry point (stdio transport)\n├── types.ts              # Shared types (tool inputs/outputs)\n├── tools/\n│   ├── check.ts          # \"Can I do X?\"\n│   ├── boundary.ts       # \"What are my limits?\"\n│   ├── record.ts         # \"This happened\"\n│   ├── escalate.ts       # \"This needs approval\"\n│   └── preview.ts        # \"What would this have blocked?\"\n├── constraints/\n│   ├── types.ts          # Constraint type definitions\n│   ├── engine.ts         # Constraint evaluation logic\n│   └── hardcoded.ts      # Test constraints (replaced by DB in Week 2+)\n└── traces/\n    ├── types.ts          # Trace type definitions\n    └── logger.ts         # In-memory + optional database persistence\n```\n\n## What's Built\n\n- 5 MCP tools: check, boundary, record, escalate, preview\n- 8 hardcoded constraints (AUTHORITY, THRESHOLD, PROHIBITION, TIMING)\n- In-memory trace store + optional database persistence via API\n- Keyword-based constraint matching\n- Database-backed constraints (GovernanceConstraint model in idealoom-database)\n- Admin UI for constraints, thresholds, authority, and exceptions\n- Escalation tool with urgency levels\n- Proof export (JSON/CSV for auditors)\n- Constraint Preview (simulate impact against trace history)\n- API key authentication\n- Governance page (Symmetry Principle — all members see constraints)\n- Traces viewer (actors see their own governance activity)\n","readmeFilename":"README.md"}