ABCM MCP Server

ABCM is an MCP and REST server library for managed agent-context workspaces.

The source checkout contains code only. Canonical project documentation is stored in the ABCM workspace castalia-public, project abcm. Its pinned service revision is recorded in abcm-documentation.lock.json.

To materialize the exact documentation snapshot for development or release validation:

ABCM_API_TOKEN=... bun run documentation:export

The default local endpoints are http://127.0.0.1:8787 for REST and http://127.0.0.1:8787/mcp for MCP. Override the documentation service URL with ABCM_BASE_URL.

For Obsidian, open the managed project directory as a vault:

C:\Users\egor\Documents\Qualia\castalia\документация\Castalia\public\abcm

This direct-folder mode is different from the bidirectional abcm-obsidian-plugin, which maps one vault folder to one server-assigned workspaceId/projectId through the scoped REST sync API. Obsidian device operations are not MCP tools; MCP remains the agent interface. The canonical integration guide is docs/integrations/obsidian.md in the ABCM workspace.

To import an independently managed Obsidian vault, select a separate source directory and enable the documentation overlay:

ABCM_DOCUMENTATION_SOURCE_PATH=/absolute/path/to/selected-vault \
docker compose \
  -f deploy/compose.config.yaml \
  -f deploy/compose.service.yaml \
  -f deploy/compose.obsidian.yaml \
  up -d

The selected directory is mounted read-only. It must not equal, contain, or be contained by the canonical workspace directory, including after symbolic links are resolved. Agents cannot provide or change this absolute path through REST or MCP; they operate only on the configured sourceId.

When the selected directory is a legacy corpus that has already been normalized into ABCM, configure fail-closed reconciliation. A workspace-owned manifest pins every sourcePath to one canonical targetPath plus both checksums. adopt-existing records provenance without overwriting the canonical bytes. Missing entries, changed checksums, duplicate targets, and absent targets are conflicts; the fallback import directory is never populated in this mode.

Centralized outcome, feedback, business-evaluation, and task-success APIs are intentionally absent. ABCM does not collect package ratings or model outputs. Repository-local fixtures and Docker benchmark runners remain available to ABCM developers and do not persist data in the service. Documentation lifecycle tools appear only when operator-selected directories are configured.

Every pull request merged into main starts the repository-owned Feature completion context benchmark workflow. It builds an isolated Docker fixture, compares direct file search with ABCM under the ordered relevance, fallback, determinism, isolation, and context-efficiency gates, and retains a machine-readable receipt for 30 days. A failed gate marks the post-merge workflow as failed; operators can rerun the same workflow manually. The benchmark never reads the live ABCM workspace or stores client feedback in the service.

To publish the complete 41-tool runtime, including versioned context-selection/v4 entrypoints and documentation lifecycle for both managed workspaces, use the full-capabilities overlay instead of the documentation-only overlay:

docker compose \
  --env-file .env.local \
  --env-file .env.full-capabilities \
  -f deploy/compose.config.yaml \
  -f deploy/compose.service.yaml \
  -f deploy/compose.full-capabilities.yaml \
  up -d --build

When the local service is exposed through OpenAI Secure MCP Tunnel, create its shared Docker network once and include the tunnel overlay on every service replacement:

docker network create abcm-runtime
docker compose \
  --env-file .env.local \
  --env-file .env.full-capabilities \
  -f deploy/compose.config.yaml \
  -f deploy/compose.service.yaml \
  -f deploy/compose.full-capabilities.yaml \
  -f deploy/compose.secure-mcp-tunnel.yaml \
  up -d --build

The overlay keeps the REST container on the tunnel network under the internal name abcm-local and admits that hostname at the MCP Host boundary. Restart tunnel-client after the REST container becomes healthy. Omitting this overlay while replacing the service leaves ChatGPT discovery with a tunnel-side 502 or Forbidden response.

Set ABCM_DOCUMENTATION_PUBLIC_SOURCE_PATH, ABCM_DOCUMENTATION_PRIVATE_SOURCE_PATH, and the separate ABCM_ARTIFACT_AMENDMENT_OPERATOR_TOKEN in an ignored operator-owned environment file. The operator token must differ from the agent API token. Restart a long-lived tunnel or connector after the runtime version or tool configuration changes so it performs a new MCP initialization and tools/list.

ABCM domain failures are completed typed MCP outcomes: structuredContent.error_code is the stable discriminator and the JSON text code must be equal. isError=true remains reserved for schema/protocol and unexpected server failures, which prevents managed connectors from replacing an ABCM domain code with a generic connector code.

Markdown tags are the source of link packages. Use frontmatter such as tags: [architecture, control-plane] or inline tags such as #architecture. On the next ScopeMap scan, ABCM exposes one virtual LinkPackage per normalized tag. File create, update, move, delete, batch apply, and documentation sync therefore update packages without a separate publish/rebase lifecycle. Package identifiers never grant access; every build is bound to its workspace and reauthorizes every selected document.

This local environment is a single-version development runtime, not production. After the replacement container is healthy and bun run runtime:inspect succeeds, remove stopped containers and versioned images of the previous ABCM server iteration. Preserve the current container/image, abcm-state, the tunnel, and the separate abcm-mcp-server:benchmark image. A retained Docker rollback version requires an explicit future parallel-version or production policy.