serena-pool

Project-aware pooling proxy for Serena MCP servers.

Serena has no built-in pooling: a stdio server dies with every client session, so each new session pays a cold start for the language servers behind it. serena-pool keeps warm, per-project Serena instances alive between sessions and shares them across clients (Codex, ZCode, Claude Code, ...) through a lightweight stdio <-> streamable-http bridge.

How it works

The proxy is a single-file Python program you register as an MCP server (stdio) in your client:

• detects the project root from the working directory (.serena/project.yml or .git upwards, fallback: cwd);

• derives a deterministic port from md5(project path + context), with linear probing on collisions and a cross-process file lock against double spawns;

• lazily starts serena start-mcp-server --transport streamable-http --project <path> as a detached, hidden-window process;

• writes a lease with a heartbeat; a detached reaper kills instances that received no fresh leases for ttl_seconds;

• bridges MCP JSON-RPC both ways (POST + SSE, session ids, 202 notifications, server pings);

• if the backing server dies, transparently restarts it and replays initialize — the client never notices;

• enforces a per-request deadline (request_timeout): a wedged server triggers reconnect/restart instead of hanging the client forever.

The same project can hold separate instances per client context (codex, zcode, ...) — see SERENA_POOL_CONTEXT below. State lives in ~/.serena/pool/:

Related MCP server: mcp-streamable-http-bridge

Install

Requires Python 3.10+ and Serena on PATH or at ~/.local/bin/serena.exe. The only dependency is httpx.

Run directly from git with uv:

uvx --from git+https://github.com/svetkis/serena-pool serena-pool

or clone and run with any interpreter that has httpx:

git clone https://github.com/svetkis/serena-pool
pip install httpx
python serena_pool_proxy.py

Client configuration

Codex (~/.codex/config.toml):

[mcp_servers.serena]
command = "C:\\path\\to\\python.exe"          # any python with httpx
args = ["C:\\path\\to\\serena_pool_proxy.py"]

ZCode (~/.zcode/cli/config.json) or any Claude-style MCP config:

{
  "mcp": {
    "servers": {
      "serena": {
        "type": "stdio",
        "command": "uvx",
        "args": ["--from", "git+https://github.com/svetkis/serena-pool", "serena-pool"],
        "env": { "SERENA_POOL_CONTEXT": "zcode" }
      }
    }
  }
}

Configuration

Global config: ~/.serena/pool/config.json (created with defaults on first run).

Environment:

• SERENA_POOL_CONTEXT — overrides context for this proxy invocation without touching the shared config. Instances are keyed per (project, context) pair, so Codex and ZCode opening the same project each get their own Serena instance with the right tool set.

Smoke test

python examples/pool_test_client.py <project_dir>

Runs initialize → tools/list → a tool call through the proxy and prints each step.

Platform status

Windows-first: process control uses msvcrt locks, taskkill /T, hidden-window creation flags and pythonw.exe for the detached reaper. Linux/macOS support is not implemented yet; patches welcome.

License

MIT. This project is an independent process that talks to Serena over its public MCP interface; it contains no Serena code. Serena itself is GPL-3.0-or-later since v2.0.0 (SolidLSP remains MIT).