coding-mcp

coding-mcp is a local MCP server for coding agents. It exposes safe repository reads, edits, skill reads, automatic command execution, and project test detection over stdio.

Install

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

Configure

Copy coding-mcp.example.toml and replace the repository and skill paths. Multiple repositories are supported; every repository tool call uses its configured id.

Repository-local AGENTS.md files are resolved first. If none apply, the selected repository's agents_fallback is used. Call repo_instructions and pass its acknowledgement to repo_write, repo_patch, command_run, and test_run.

Run

.venv/bin/coding-mcp --config /absolute/path/to/coding-mcp.toml

Example MCP client configuration:

{
  "mcpServers": {
    "coding-mcp": {
      "command": "/absolute/path/to/coding-mcp/.venv/bin/coding-mcp",
      "args": ["--config", "/absolute/path/to/coding-mcp.toml"]
    }
  }
}

Agent workflow: build a project from scratch

The agent works inside an existing empty directory that has been registered as an approved repository. The MCP server does not create arbitrary directories outside its configuration.

1. Call repo_list_repositories and select the repository id.

2. Call repo_instructions(repository_id, path) before making changes. This reads the applicable repository AGENTS.md; when none exists, it reads the configured agents_fallback. Save the returned acknowledgement value.

3. Call skill_list and skill_read to load relevant development instructions.

4. Inspect the workspace with repo_list and repo_read.

5. Create files with repo_write, passing agents_ack. Use repo_patch for targeted edits and expected_sha256 when editing a file that was previously read.

6. Call test_detect, then test_run with the same acknowledgement. Use command_run for builds, linters, formatters, generators, or other language tooling; commands are discovered automatically and do not need configuration entries.

7. Re-read changed files and rerun verification after fixes.

Example initial tool sequence:

repo_list_repositories()
repo_instructions(repository_id="new-app", path="")
skill_list()
skill_read(path="relevant-skill/SKILL.md")
repo_list(repository_id="new-app", path="")
repo_write(
  repository_id="new-app",
  path="pyproject.toml",
  content="...",
  agents_ack="<acknowledgement>"
)
test_detect(repository_id="new-app")
test_run(repository_id="new-app", agents_ack="<acknowledgement>")

repo_write creates files but does not create missing parent directories. Pre-create directories or explicitly allow a safe mkdir -p command and run it through command_run after acknowledging AGENTS.md.

Safety model

• Repository paths are relative to named, approved roots.

• Absolute paths, traversal, and symlink escapes are rejected.

• Writes are atomic and can require an expected SHA-256 revision.

• Exact patches must match once.

• Commands are automatic and use shell=False; they run from the selected repository.

• Commands have configurable timeout and output limits.

• Because command execution is unrestricted by an allowlist, only connect trusted local agents to this server.

• The server does not expose arbitrary filesystem paths.

Run tests with:

.venv/bin/python -m pytest