MCPSystem

MCPSystem is a local runtime for persistent, isolated replicas of services such as GitHub, GitLab, Bitbucket, Jira, Linear, and YouTrack. External services are sources of API contracts and optional conformance checks; they are not runtime dependencies.

The MCP service foundation milestone is complete. It provides:

• a versioned service-plugin contract;

• a persistent control plane;

• isolated per-environment service databases;

• transactional plugin migrations and seeding;

• persisted selection of MCP surfaces;

• strict TOML environment/template configuration;

• immutable templates and isolated clone-on-create environments;

• immutable point-in-time environment snapshots, independent snapshot clones, and structured SQL/Git snapshot diffs;

• restart and isolation guarantees covered by tests.

• a durable, transport-neutral provider operation log.

Task generation, benchmark scenarios, perturbation-time ground truth, filtering, and the Oracle are the next benchmark-harness layer; they are intentionally outside the completed MCP service foundation.

Built-in service plugins

The built-in github@0.1.0 plugin provides SQLite and PostgreSQL schemas for the core software-company resources and a deterministic minimal bootstrap. Its first transactional operation set covers repositories, issues, labels, assignees, comments, relational commit/branch state, pull requests, requested reviewers, reviews, review comments, and merge transitions. Each environment also owns isolated local bare-Git repositories containing the real blobs, trees, commits, and refs. Contract provenance and the current coverage boundary are documented in docs/services/github.md.

The bounded gitlab@0.1.0 core adds groups/projects, labels, issues/notes, repository files/commits/branches/tags, merge requests/discussions/approvals, pipelines/jobs/statuses, and releases. It preserves the same SQLite/PostgreSQL isolation and real-Git guarantees and exposes 78 agent-facing MCP tools through gitlab_rest_v4 plus 78 HTTP routes under /api/v4. The CI-verdict writer is admin-only so an agent cannot forge a green build.

The bounded jira@0.1.0 core adds users, projects, issues, comments, workflow transitions, issue links, Scrum boards, and sprint lifecycle. Its jira_rest_v3 MCP surface exposes 22 tools backed by isolated relational state.

The six built-in surfaces expose 221 agent-facing tools in the combined company template through a stateful MCP 2025-11-25 JSON-RPC stdio server. Environment, actor, and service routing are fixed when the server starts rather than accepted from model-controlled tool arguments. Setup and protocol details are in docs/mcp.md.

Agents connect directly to these local, contract-compatible MCP surfaces. The GitHub and GitLab REST implementations remain useful for conformance testing, but no vendor MCP process or external service is part of the runtime.

For a combined six-service environment and role-bound client config, run scripts/materialize_company.py followed by scripts/generate_mcp_config.py. Exact commands are in docs/mcp.md.

MCP and HTTP provider calls are recorded in the same persistent operation timeline for future task inspection and standup/release artifacts. Every entry carries a monotonic per-environment seq, so a caller can ask "what has this actor done since I last looked". See docs/operation-log.md.

An external harness drives all of this in process: it creates and deletes environments, freezes one for the duration of a snapshot, and exports a byte-stable image of a whole world. Those primitives and the reasoning behind each are in docs/harness-integration.md; the two-service environment they use is configs/templates/aabench-gitlab-jira.toml.

The completed boundary is deliberately bounded: local agents use MCP over stdio, and repository work uses explicit provider-shaped commit/file/branch operations backed by real bare Git. Streamable HTTP MCP, Git smart protocol, working-tree checkout, and complete vendor-wide API parity are excluded until a benchmark workflow requires them.

Inspect environments and their MCP/HTTP operation timeline in the local read-only UI:

PYTHONPATH=src .venv/bin/python scripts/inspector.py --data-root data --port 8777

The Inspector projects all six providers into the same author-facing model: repositories/projects, tickets/issues, pull/merge requests, reviews/approvals, real Git diffs, Actions/pipelines, and Jira project tickets. Built-in templates live under configs/templates/.

Then open http://127.0.0.1:8777. The UI and its loopback-only security boundary are documented in docs/inspector.md. Its Artifacts workbench uses provider-neutral ticket/change-set/review/build projections rather than copying the GitHub interface.

Materialize the GitHub template and one isolated PostgreSQL environment:

MCP_SYSTEM_POSTGRES_DSN=postgresql://mcp_system:mcp_system@127.0.0.1:55432/mcp_system \
  .venv/bin/python scripts/materialize_github.py

Run its MCP server after substituting the printed environment id:

.venv/bin/python scripts/mcp_server.py \
  --environment ENVIRONMENT_ID \
  --actor engineer \
  --postgres-dsn postgresql://mcp_system:mcp_system@127.0.0.1:55432/mcp_system

Related MCP server: CodexPro Runtime

Run tests

PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -v

PostgreSQL backend

Start the local PostgreSQL 18 instance:

docker compose up -d --wait postgres

Construct the runtime with persisted PostgreSQL control and service schemas:

from pathlib import Path
from mcp_system import MCPSystem, PluginRegistry

registry = PluginRegistry()
# Register service plugins before opening or creating environments.

system = MCPSystem.with_postgres(
    Path("data"),
    registry,
    "postgresql://mcp_system:mcp_system@127.0.0.1:55432/mcp_system",
)

Run PostgreSQL integration tests:

MCP_SYSTEM_TEST_POSTGRES_DSN=postgresql://mcp_system:mcp_system@127.0.0.1:55432/mcp_system \
  .venv/bin/python -m unittest discover -s tests -v

Declarative environment

[environment]
name = "local software company"
mcp_surfaces = ["github_standard", "codebase"]

[[services]]
instance_id = "code_host"
plugin = "github"
version = "1.0.0"

[services.seed]
organization = "acme"

Template configuration uses the same services array with a [template] header containing id, name, version, and mcp_surfaces.