atlasent-mcp-server: Instructions file for Claude Code

@atlasent/mcp-server

MCP server that enforces authorize-before-execute for any MCP-compatible AI agent.

Architecture baseline

Canonical cross-repo reference: atlasent-docs/architecture/ARCHITECTURE-BASELINE.md

This repo's role: MCP distribution layer — exposes AtlaSent authorization as MCP tools (atlasent_evaluate, atlasent_verify_permit) for any MCP-compatible agent host (Claude Desktop, Cursor, Windsurf) without requiring a custom SDK integration.

Cross-repo invariants for this repo:

• Wire shape source of truth: atlasent-api/supabase/functions/v1-{evaluate,verify-permit}/handler.ts. Do not invent new request/response shapes here.
• Fail-closed at every layer: any error in authorize() or verify() collapses to deny. This is non-negotiable.
• 10-second request timeout on every hosted-API fetch (AbortSignal.timeout()). A hung API must not block the agent.
• Mode dispatch reads env vars at call time (not module load), so tests can swap config without reload.

Architecture

src/
  decision.ts                   Decision / VerifyResult types + toolResult() MCP envelope helper
  localEngine.ts                Tiny rules engine used when no hosted backend is configured
  engine.ts                     authorize() / verify(): dispatches to local or remote; fail-closed wrapper
  server.ts                     createServer(): registers evaluate, verify_permit, deploy_service + 20+ tools
  canonCatalog.ts               GENERATED-DERIVED: the canonical action specs incl. canon_id (from the atlasent repo); backs atlasent_lookup_action. Re-sync with scripts/sync-canon.mjs
  canonGraph.ts                 GENERATED-DERIVED: per-action knowledge-graph neighborhood + compliance (from atlasent/generated/authorization-graph.json); enriches atlasent_lookup_action. Re-sync with scripts/sync-canon.mjs
  atlasCatalog.ts               GENERATED-DERIVED: the Knowledge Atlas (concepts + edges, from atlasent-docs/architecture/traceability/atlas.json); backs atlasent_atlas_lookup. Re-vendor with scripts/vendor-atlas.mjs
  v2Tools.ts                    Wave B tools: atlasent_evaluate_many, atlasent_evaluate_stream, atlasent_query
  v2Client.ts                   HTTP clients for Wave A endpoints; FeatureNotEnabledError on 404
  complianceTools.ts            SCIM, SIEM config, evidence export MCP tools
  vqpTools.ts                   VQP snapshot generation, verification, drift event tools
  streamableHttp.ts             Streamable HTTP transport (MCP HTTP mode)
  index.ts                      CLI entry point; connects stdio transport
  server.test.ts                Unit tests: tools/list, evaluate (local + remote), verify_permit, deploy_service
  server.readonly.test.ts       READONLY mode tests
  complianceTools.test.ts       Compliance tool unit tests
  v2Tools.test.ts               V2 Wave B tool unit tests
  v2Client.test.ts              V2 HTTP client unit tests
  streamableHttp.integration.test.ts  Streamable HTTP transport integration tests
  integration.test.ts           Live-API tests; require ATLASENT_API_KEY + ATLASENT_BASE_URL, skip otherwise
  integration.write.test.ts     Live-API write tests (mutating tools)

examples/
  demo.mjs            End-to-end script: spawns server, drives evaluate -> deploy -> verify flow

.github/workflows/
  ci.yml              build + test on push/PR, Node 18/20/22 matrix
  integration.yml     nightly integration tests against the hosted API
  publish.yml         npm publish --access public (cosign-signed tarball) on v* tag push, gated by an AtlaSent release check