Skip to main content
Glama
aoci-mcp-multi

aoci-mcp-multi

by Dynastxu
README.md
# aoci-mcp-multi

English | [中文](README.zh.md)

One MCP server for many [AOCI-CODE](https://github.com/aoci-spec/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`

## Run

```bash
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):

```json
{
  "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`](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:

```bash
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:

```bash
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.

```bash
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