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
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data