# 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

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

## Configure

Copy [`coding-mcp.example.toml`](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

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

Example MCP client configuration:

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

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

```bash
.venv/bin/python -m pytest
```