coding-tools-mcp-server

# Coding Tools MCP Server > Skill by [ara.so](https://ara.so) — MCP Skills collection. ## Overview Coding Tools MCP is a model-neutral coding-agent runtime MCP server that exposes local coding primitives to any MCP client. It provides safe, workspace-bounded operations for: - **File operations**: read, list, search files with automatic exclusion of build artifacts - **Structured patching**: apply unified diff patches to files - **Command execution**: run shell commands with safety controls, timeouts, and permission gates - **Git operations**: status, diff, log, show, blame (read-only git inspection) - **Interactive sessions**: manage stdin for long-running processes - **Image viewing**: inspect image files with optional auto-resize The server enforces workspace boundaries, rejects path traversal, blocks sensitive environment variables, and provides configurable permission modes. ## Installation ### Quick Install (Standalone) ```bash # Install from PyPI curl -fsSL https://raw.githubusercontent.com/xyTom/coding-tools-mcp/main/scripts/install.sh | bash # Or run without persistent install uvx coding-tools-mcp --workspace /path/to/repo ``` ### Install with HTTP Server ```bash # Start local HTTP server curl -fsSL https://raw.githubusercontent.com/xyTom/coding-tools-mcp/main/scripts/install.sh \ | bash -s -- --start --workspace /path/to/repo # Exposed at http://127.0.0.1:8765/mcp ``` ### Install with Development Dependencies ```bash # From source checkout git clone https://github.com/xyTom/coding-tools-mcp.git cd coding-tools-mcp python -m pip install -e ".[dev]" # With image support for view_image auto-resize python -m pip install -e ".[image]" ``` ## MCP Client Configuration ### Claude Code Add to `claude_desktop_config.json`: ```json { "mcpServers": { "coding-tools": { "command": "uvx", "args": ["coding-tools-mcp", "--stdio", "--workspace", "/path/to/repo"] } } } ``` ### Cursor Add to Cursor's MCP settings: ```json { "mcpServers": { "coding-tools": { "command": "uvx", "args": ["coding-tools-mcp", "--stdio", "--workspace", "/path/to/repo"] } } } ``` ### Generic TOML Configuration ```toml [mcp_servers.coding_tools] command = "uvx" args = ["coding-tools-mcp", "--stdio", "--workspace", "/path/to/repo"] ``` ### HTTP Client Configuration For Streamable HTTP clients using protocol version `2025-06-18`: ```bash # Start server coding-tools-mcp --workspace /path/to/repo # Client connects to # URL: http://127.0.0.1:8765/mcp ``` ## Permission Modes The server has three permission modes: ### Safe Mode (Default) ```bash coding-tools-mcp --permission-mode safe --workspace /path/to/repo ``` - Blocks shell expansion (`$VAR`, `$(command)`, glob patterns) - Blocks network-looking commands - Checks for destructive operations - Filters sensitive environment variables - Requires explicit permission for risky operations ### Trusted Mode (Local Development) ```bash coding-tools-mcp --permission-mode trusted --workspace /path/to/repo # Or with inherited environment CODING_TOOLS_MCP_SHELL_ENV_INHERIT=all \ coding-tools-mcp --permission-mode trusted --workspace /path/to/repo ``` - Allows shell expansion for local toolchains - Allows dependency downloads - Allows inline interpreter snippets - Still filters secrets and destructive commands ### Dangerous Mode (Isolated Environments Only) ```bash coding-tools-mcp --permission-mode dangerous --workspace /path/to/repo ``` - Disables all `exec_command` permission gates - **Only use inside isolated containers or VMs** - Workspace path boundaries still apply for file operations ## Core Tools ### File Operations #### read_file ```python # Request { "path": "src/main.py", "start_line": 10, # optional "end_line": 50 # optional } # Response includes file content, encoding detection, and metadata ``` #### list_dir ```python # Request { "path": "src", "recursive": False } # Returns directory listing with file types ``` #### list_files ```python # Request { "path": ".", "pattern": "*.py", # optional glob "recursive": True } # Returns filtered file list excluding .git, node_modules, etc. ``` #### search_text ```python # Request { "query": "def authenticate", "path": "src", "case_sensitive": False, "regex": False, "max_results": 100 } # Returns matching files with line numbers and context ``` ### Patching #### apply_patch ```python # Request { "patch": """--- a/src/config.py +++ b/src/config.py @@ -10,3 +10,4 @@ DEBUG = False +FEATURE_FLAG = True """, "dry_run": False # optional: preview without applying } # Applies unified diff format patches # Validates patch format and target file existence ``` ### Command Execution #### exec_command ```python # Request { "command": "pytest tests/test_auth.py -v", "cwd": ".", # optional, workspace-relative "timeout": 30, # optional, seconds "capture_output": True, # optional "env": { # optional additional env vars "PYTEST_ARGS": "--maxfail=1" } } # Response includes stdout, stderr, exit_code, and warnings # Session ID returned for interactive processes ``` **Safety features:** - Workspace-bounded working directory - Timeout enforcement (default 30s for one-shot, 3600s for sessions) - Output caps (1MB stdout, 256KB stderr per command) - Sensitive value filtering in environment - Destructive command checks - Network command permission gates (in safe mode) - Shell expansion gates (in safe mode) - Landlock filesystem confinement on supported Linux hosts #### write_stdin ```python # Request { "session_id": "exec_abc123", "data": "yes\n" # send input to running process } # For interactive command sessions ``` #### kill_session ```python # Request { "session_id": "exec_abc123", "signal": "SIGTERM" # optional, defaults to SIGTERM } # Terminates long-running command session ``` ### Git Operations (Read-Only) #### git_status ```python # Request { "cwd": "." # optional, workspace-relative } # Returns working tree status ``` #### git_diff ```python # Request { "cwd": ".", "staged": False, # optional: show staged changes "paths": ["src/"] # optional: limit to paths } # Returns unified diff of changes ``` #### git_log ```python # Request { "cwd": ".", "max_count": 20, # optional "path": "src/main.py" # optional: file history } # Returns commit history ``` #### git_show ```python # Request { "cwd": ".", "revision": "HEAD~1", # commit hash or ref "path": "src/config.py" # optional: specific file } # Shows commit or file content at revision ``` #### git_blame ```python # Request { "path": "src/main.py", "start_line": 10, # optional "end_line": 50 # optional } # Returns line-by-line commit attribution ``` ### Workspace Management #### get_default_cwd ```python # Request: {} # Returns current default working directory (workspace-relative) ``` #### set_default_cwd ```python # Request { "cwd": "services/api" # workspace-relative path } # Sets default working directory for subsequent commands ``` #### server_info ```python # Request: {} # Returns workspace root, permission mode, profile, platform info ``` #### view_image ```python # Request { "path": "assets/logo.png", "max_dimension": 1024 # optional: auto-resize } # Returns base64-encoded image data with MIME type # Requires [image] extra for resize support ``` ### Permission Management #### request_permissions ```python # Request { "permissions": ["network", "shell_expansion"], "reason": "Need to download dependencies with npm install" } # Request explicit permission for gated operations # Client may prompt user or auto-approve based on policy ``` ## Tool Profiles Control which tools are exposed: ```bash # Full profile (default): all tools with truthful annotations coding-tools-mcp --workspace /path/to/repo # Read-only profile: safe for remote/untrusted clients # Only inspection, git read, image view, and cwd helpers CODING_TOOLS_MCP_TOOL_PROFILE=read-only coding-tools-mcp --workspace /path/to/repo # Compat readonly: exposes all tools but marks all as read-only # NOT a safety mode - mutation tools still work CODING_TOOLS_MCP_TOOL_PROFILE=compat-readonly-all coding-tools-mcp --workspace /path/to/repo ``` ## Remote MCP Setup ### Bearer Token Auth (Recommended for Testing) ```bash # Anonymous read-only tunnel (testing only) CODING_TOOLS_MCP_AUTH_MODE=noauth \ CODING_TOOLS_MCP_TOOL_PROFILE=read-only \ ./scripts/tunnel.sh cloudflared /path/to/repo # Bearer token auth with custom token CODING_TOOLS_MCP_AUTH_MODE=bearer \ CODING_TOOLS_MCP_BEARER_TOKEN="your-secret-token-here" \ ./scripts/tunnel.sh cloudflared /path/to/repo # Client configuration: # URL: https://<tunnel-host>/mcp # Header: Authorization: Bearer your-secret-token-here ``` ### OAuth 2.1 Auth (For Production Clients) ```bash # OAuth with Authorization Code + PKCE CODING_TOOLS_MCP_AUTH_MODE=oauth \ ./scripts/tunnel.sh cloudflared /path/to/repo # Script prints generated OAuth password # Server infers issuer from tunnel URL # Accepts any non-empty client_id by default # Optional: pin issuer and client credentials CODING_TOOLS_MCP_AUTH_MODE=oauth \ CODING_TOOLS_MCP_SERVER_URL=https://your-domain.com \ CODING_TOOLS_MCP_OAUTH_CLIENT_ID=client-id \ CODING_TOOLS_MCP_OAUTH_CLIENT_SECRET=client-secret \ ./scripts/tunnel.sh cloudflared /path/to/repo ``` ### Supported Tunnels ```bash # Cloudflared scripts/tunnel.sh cloudflared /path/to/repo # ngrok scripts/tunnel.sh ngrok /path/to/repo # Microsoft Dev Tunnel scripts/tunnel.sh devtunnel /path/to/repo # Auto-install tunnel CLI if missing scripts/install.sh --tunnel cloudflared --auto-install-tunnel --workspace /path/to/repo ``` ## Common Patterns ### Python Project Test Run ```python # 1. Check repository structure list_files({"path": ".", "recursive": True}) # 2. Read test configuration read_file({"path": "pytest.ini"}) # 3. Check git status before running tests git_status({"cwd": "."}) # 4. Run specific test file exec_command({ "command": "pytest tests/test_api.py -v --tb=short", "timeout": 60 }) # 5. Check for changes after test (e.g., coverage reports)