Coding MCP

Production-ready MCP server that lets AI agents perform coding tasks on remote repositories.

What is it?

coding-mcp is an MCP (Model Context Protocol) server that exposes your code repositories as a set of tools and resources that AI agents can use to read, write, search, and run commands — all without the agent needing local access to the repositories.

Primary goal: deploy one server on a machine that hosts your code, then connect any MCP-compatible agent (Claude, Cursor, etc.) to it. The agent can browse files, edit code, run builds and tests, manage git, and more — all through structured MCP tool calls.

┌──────────────────────────────────────────────┐
│  AI Agent (Claude / Cursor / any MCP client) │
└────────────────┬─────────────────────────────┘
                 │  MCP over HTTP or STDIO
                 ▼
┌──────────────────────────────────────────────┐
│           coding-mcp server                  │
│  (runs on the machine with your repos)       │
│                                              │
│  Tools: files · git · search · commands      │
│  Resources: project index · file content     │
│  Prompts: implement · review · fix tests     │
└──────────────────┬───────────────────────────┘
                   │  filesystem + git
                   ▼
      /projects/repo-a  /projects/repo-b  …

Documentation

Quickstart: https://coding-mcp.omaicode.com
API Reference: https://coding-mcp.omaicode.com/api-reference
Source Code Analysis: https://coding-mcp.omaicode.com/architecture/source-code-analysis
CLI and Registry Guide: https://coding-mcp.omaicode.com/guides/cli-and-registry

Highlights

Multi-project registry with persistent indexing
Safe file operations and patching (structured edits + unified diff hunks)
Git command suite with structured output
Allowlist-based command runner with timeout and output limits
Binary-safe file resources (text and base64 blob modes)
Dual transport support: STDIO and HTTP (streamable or SSE)
HTTP API-key authentication + RBAC (viewer/editor/admin)
OpenTelemetry hooks for request and tool-level tracing
Structured operation envelopes with request IDs and timing
Audit logging for mutating actions

Quick Start

Install globally:

npm install -g @kieutrongthien/coding-mcp

coding-mcp init /projects

Start the server:

# HTTP transport (for remote agents)
coding-mcp serve --transport http --host 0.0.0.0 --port 4000 --mode streamable

# STDIO transport (for local agents like Cursor or Claude Desktop)
coding-mcp serve --transport stdio

Build from source

git clone https://github.com/kieutrongthien/coding-mcp.git
cd coding-mcp
cp .env.example .env
npm install
npm run build
npm install -g .

CLI Commands

Command	Description
`coding-mcp init [path]`	Scan a directory for projects and write the registry. Defaults to the current working directory.
`coding-mcp add <path>`	Add a new root directory to the project registry.
`coding-mcp remove <path>`	Remove a root directory from the project registry.
`coding-mcp serve`	Start the MCP server. Accepts `--transport`, `--host`, `--port`, and `--mode` flags.

Development shortcuts (no build step needed):

npm run dev:stdio
npm run dev:http
npm run dev:serve -- --transport http --host 127.0.0.1 --port 3001 --mode sse

MCP Tools

Tools are the primary interface for agents. Each tool accepts a project_id (returned by list_projects) and operates within that project's root, preventing any path traversal outside it.

Project Tools

Tool	Description
`list_projects`	List all projects discovered in the configured root directories.
`get_project`	Get metadata for a specific project (path, detected tooling, package manager, git info).
`refresh_project_index`	Re-scan one project or all projects to pick up newly added repositories.

File Tools

Tool	Description
`list_directory`	List files and subdirectories at a given path within a project.
`read_file`	Read file content, optionally limited to a line range.
`read_multiple_files`	Read multiple files in a single call.
`create_file`	Create a new file. Set `overwrite: true` to replace an existing file.
`write_file`	Overwrite the full content of an existing file.
`replace_in_file`	Find and replace text within a file (first match or all matches).
`apply_patch`	Apply a unified diff or a list of structured edit operations to a file.
`delete_file`	Delete a file or directory. Requires `confirm: true` as a safety guard.
`move_file`	Move or rename a file or directory.

Search Tools

Tool	Description
`search_files`	Search for files by name or path pattern within a project.
`grep_content`	Search file contents using a regex-like pattern. Returns matching lines with file paths and line numbers.
`get_project_tree`	Get the directory tree of a project up to a configurable depth.
`summarize_project`	Return a summary of the project stack, package manager, detected tooling, and top-level tree.

Git Tools

Tool	Description
`git_status`	Show the current working tree status (modified, staged, untracked files).
`git_diff`	Show unstaged or staged changes as a unified diff.
`git_branch_list`	List all local and remote branches.
`git_checkout_branch`	Switch to an existing branch.
`git_checkout_new_branch`	Create and switch to a new branch.
`git_pull`	Pull the latest changes from the remote.
`git_add`	Stage one or more files or paths.
`git_restore`	Discard working tree changes for specified paths. Requires `confirm: true`.
`git_commit`	Create a commit with the given message.
`git_push`	Push commits to a remote branch. Supports `set_upstream`.
`git_log`	Show recent commit history with configurable limit.
`git_show`	Show details of a specific commit, tag, or git object by ref.
`git_create_tag`	Create an annotated tag.

Command Tools

Commands run inside the project directory. Only commands on the ALLOWED_COMMANDS allowlist are permitted.

Tool	Description
`run_build`	Run the build command auto-detected from the project tooling (e.g. `npm run build`, `make`).
`run_test`	Run the test command auto-detected from the project tooling (e.g. `npm test`, `pytest`).
`run_lint`	Run the lint command auto-detected from the project tooling (e.g. `npm run lint`, `ruff`).
`run_command_safe`	Run any allowlisted command with explicit arguments, working directory, and timeout.

MCP Resources

Resources expose read-only data that agents can fetch directly by URI.

Resource URI	Description
`project://index`	JSON list of all indexed projects.
`project://{project_id}/tree`	Directory tree of the project (depth 4).
`project://{project_id}/readme`	Raw content of the project's `README.md`.
`project://{project_id}/package-json`	Raw content of the project's `package.json`.
`project://{project_id}/git-status`	Current git status as JSON.
`project://file/{project_id}/{path}`	Content of any file. Text files are returned as `text`; binary files as base64 `blob`.
`project://file-meta/{project_id}/{path}`	Metadata of a file (size, MIME type, encoding, truncation status).

MCP Prompts

Prompts provide pre-built instructions that agents can invoke to start structured coding workflows.

Prompt	Description
`analyze-project`	Ask the agent to analyze a project's architecture, risks, and improvements.
`implement-task`	Ask the agent to implement a described task within a project.
`explain-file`	Ask the agent to explain how a specific file works.
`generate-commit-message`	Ask the agent to generate a conventional commit message from a diff summary.
`review-diff`	Ask the agent to review a diff for bugs, regressions, and missing tests.
`fix-test-failures`	Ask the agent to fix failing tests given raw test output.

MCP Client Examples

Claude Desktop (STDIO)

{
  "mcpServers": {
    "coding-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/coding-mcp/dist/src/main/stdio.js"],
      "env": {
        "PROJECTS_ROOTS": "/projects"
      }
    }
  }
}

Cursor (STDIO)

{
  "mcpServers": {
    "coding-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/coding-mcp/dist/src/main/stdio.js"],
      "env": {
        "PROJECTS_ROOTS": "/projects,/srv/repos",
        "ENABLE_STDIO": "true",
        "ENABLE_HTTP": "false"
      }
    }
  }
}

Generic HTTP MCP client

{
  "mcpServers": {
    "coding-mcp-http": {
      "url": "http://your-host:4000",
      "headers": {
        "x-api-key": "editor-key"
      }
    }
  }
}

Configuration

Use environment variables directly or provide a JSON/YAML config file via MCP_CONFIG_PATH.

Core settings

Variable	Description
`PROJECTS_ROOTS`	Comma-separated list of root directories to scan for projects (preferred).
`PROJECTS_ROOT`	Single root directory (legacy compatibility).
`ENABLE_HTTP`	Enable the HTTP transport (`true`/`false`).
`ENABLE_STDIO`	Enable the STDIO transport (`true`/`false`).
`HTTP_HOST`	HTTP server bind address (default `127.0.0.1`).
`HTTP_PORT`	HTTP server port (default `3000`).
`HTTP_MODE`	HTTP transport mode: `streamable` or `sse`.
`MAX_FILE_SIZE`	Maximum file size for read operations (bytes).
`MAX_OUTPUT_SIZE`	Maximum command or resource output size (bytes).
`COMMAND_TIMEOUT_MS`	Timeout for command execution (milliseconds).
`RETRY_MAX_ATTEMPTS`	Number of retry attempts for transient failures.
`RETRY_BASE_DELAY_MS`	Base delay between retries (milliseconds).
`ALLOWED_COMMANDS`	Comma-separated list of commands permitted by `run_command_safe`.
`PROTECTED_PATHS`	Comma-separated path patterns that cannot be modified.
`LOG_LEVEL`	Log verbosity: `trace`, `debug`, `info`, `warn`, `error`.
`REGISTRY_FILE`	Path to the project registry JSON file.
`AUDIT_LOG_FILE`	Path to the audit log for mutating operations.
`HTTP_REQUEST_LOG_FILE`	Path to the HTTP request log.

Security settings

Variable	Description
`ENABLE_AUTH`	Enable API-key authentication for the HTTP transport.
`AUTH_HEADER_NAME`	HTTP header used to pass the API key (default `x-api-key`).
`AUTH_API_KEYS`	Comma-separated list of keys in `key:role:id` format.

Observability settings

Variable	Description
`ENABLE_OTEL`	Enable OpenTelemetry tracing.
`OTEL_SERVICE_NAME`	Service name reported in traces.
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP HTTP endpoint for trace export.
`OTEL_EXPORTER_OTLP_HEADERS`	Headers for the OTLP exporter in `key=value,key2=value2` format.

HTTP Security (Auth/RBAC)

Enable API-key authentication when exposing the HTTP transport to external agents.

ENABLE_AUTH=true
AUTH_HEADER_NAME=x-api-key
AUTH_API_KEYS=viewer-key:viewer:viewer1,editor-key:editor:editor1,admin-key:admin:admin1

Pass the key in the request header:

x-api-key: editor-key

Roles:

Role	Permissions
`viewer`	Read-only operations
`editor`	Read + non-destructive write, build, and test operations
`admin`	Full access including destructive operations

HTTP Monitoring Endpoints

When HTTP transport is enabled:

Endpoint	Description
`GET /healthz`	Liveness check
`GET /readyz`	Readiness check with indexed project count
`GET /metrics`	Basic metrics: `request_count`, `error_count`, latency summary

OpenTelemetry

Tracing can be exported over OTLP HTTP:

ENABLE_OTEL=true
OTEL_SERVICE_NAME=coding-mcp
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer%20token

Emitted spans:

mcp.http.request
mcp.tool.{operation}

Response Contract

All tool responses follow the same envelope format.

Successful operation:

{
  "ok": true,
  "project_id": "abc123",
  "operation": "read_file",
  "data": {},
  "warnings": [],
  "errors": [],
  "request_id": "uuid",
  "duration_ms": 12
}

Failed operation:

{
  "ok": false,
  "operation": "write_file",
  "error_code": "SECURITY_ERROR",
  "message": "Operation blocked for protected path",
  "details": {},
  "request_id": "uuid",
  "duration_ms": 7
}

Architecture

The server uses one shared core with modular layers:

config: environment/config-file loading and runtime validation
core: response contracts, errors, logging, telemetry hooks, locks
services: filesystem, git, patching, command execution, auth, project registry
mcp: tool/resource/prompt registries bound to shared services
main: CLI and transport bootstrap (stdio, http, serve/init/add/remove)

STDIO and HTTP transports share the same service layer, keeping behavior consistent while allowing transport-specific controls (such as HTTP authentication).

Validation

npm run typecheck
npm test

License

MIT

Coding MCP Server