Skip to main content
Glama
aoci-mcp-multi

aoci-mcp-multi

by Dynastxu

aoci-mcp-multi

English | 中文

One MCP server for many AOCI-CODE repositories.

Instead of registering one MCP server per project — which adds every project's tool schemas to every request and leaves a dead entry behind each time a project is retired — this proxy publishes one aoci tool set and routes each call by an absolute repo argument.

  • One tool set, N repositories. The host connects once; the model adds a repo path to each call.

  • Dynamic project set. A repository's aoci mcp backend starts on first use and is reaped when idle, so starting or deleting a project never changes host configuration.

  • Validated targets. A call is refused unless the path is an absolute, existing, AOCI-initialized repository (aoci.txt or .aoci/config.json).

  • No aoci changes. Index, governance, and protocol semantics stay inside aoci mcp; the proxy only supervises and forwards.

Requirements

  • Node.js >=22.19

  • An aoci binary reachable through PATH or AOCI_BIN

  • Each target repository initialized with aoci init and aoci scan

Related MCP server: proxy-mcp

Run

npx -y @dynastxu/aoci-mcp-multi                # published package
node /path/to/aoci-mcp-multi/dist/server.js    # checkout (run pnpm run build first)

Host configuration

Any MCP host works, since this is a plain stdio server.

Claude Code / Codex / Cursor (.mcp.json or the host's equivalent):

{
  "mcpServers": {
    "aoci": {
      "command": "npx",
      "args": ["-y", "@dynastxu/aoci-mcp-multi"],
      "env": {
        "AOCI_BIN": "/usr/local/bin/aoci",
        "AOCI_ALLOWED_ROOTS": "/home/me/code"
      }
    }
  }
}

DeepSeek Harness: use the configuration-only bundle in integrations/dsh (edit the script path first), or paste an equivalent @deepseek-ai/dsh-mcp-client row with serverName: aoci.

The model then sees mcp__aoci__aoci_overview, mcp__aoci__aoci_maintain, and the rest of the catalog, each with one extra repo property.

Configuration

Variable

Default

Meaning

AOCI_BIN

aoci

Path to the aoci executable

AOCI_DEFAULT_REPO

unset

Repository used when a call omits repo; when unset, repo is required

AOCI_ALLOWED_ROOTS

unset

Delimiter-separated directories; a repo outside them is refused

AOCI_POOL_MAX

6

Maximum live backends; the least recently used one is evicted

AOCI_IDLE_MS

600000

Idle time before a backend is stopped

AOCI_SWEEP_MS

30000

Idle-scan interval

AOCI_CALL_TIMEOUT_MS

180000

Per-tool-call timeout; a stuck backend is dropped

AOCI_STARTUP_TIMEOUT_MS

30000

Handshake budget for a new backend

AOCI_DEBUG

unset

1 logs backend starts, reaps, and evictions to stderr

How it works

host  ──mcp__aoci__* ──▶  proxy  ──▶  aoci mcp --repo A     (started on first use)
                          │      └─▶  aoci mcp --repo B
                          └── one tool catalog, one stdio connection

The published catalog is captured from a real aoci backend, so schemas match aoci exactly; only the repo property is added. tools/call removes repo before forwarding, and every backend keeps its own child process, so two repositories never share protocol state.

After upgrading aoci, refresh the catalog and review the diff:

node scripts/refresh-catalog.mjs /path/to/any/initialized/repository

Limits

  • One backend per repository, shared by every session in the host scope. That matches what a single-MCP-per-repository setup does; it is not a per-session sandbox. Two sessions calling into the same repository share that backend's connection.

  • repo is required unless AOCI_DEFAULT_REPO is set.

  • The catalog is a snapshot. A new aoci tool or schema change needs refresh-catalog (or a new package release).

  • A timed-out call drops its backend, so an interrupted overview chain starts from a fresh backend on the next call — aoci re-issues its challenge in that case, which is the intended recovery.

Test

The end-to-end tests start the built proxy against two fixture repositories:

mkdir -p .testrepos/alpha .testrepos/beta   # plus a few source files
aoci --repo .testrepos/alpha init && aoci --repo .testrepos/alpha scan
aoci --repo .testrepos/beta  init && aoci --repo .testrepos/beta  scan

pnpm install --frozen-lockfile
AOCI_BIN=/path/to/aoci pnpm test             # builds, then runs vitest

The tests are integration tests: they spawn dist/server.js, speak MCP over stdio, and start real aoci backends, which is why they are slower than unit tests. A host that blocks piped child processes (for example an agent sandbox) cannot run them.

Development

TypeScript sources are built with Vite into a single dist/server.js; the catalog and package version are inlined, so the bundle has no runtime file dependency.

pnpm run build        # vite build -> dist/server.js (+ sourcemap)
pnpm run typecheck    # tsc --noEmit
pnpm run test         # build, then vitest run
pnpm run lint         # oxlint
pnpm run format       # oxfmt
pnpm run check        # typecheck + lint + format check + test

src/catalog.json is a snapshot captured from a live aoci backend; regenerate it after upgrading aoci and review the diff.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers