🥥 Context Coder MCP

Context Coder (aka. Coco) provides AI models with an MCP tools to load your entire codebase into the LLM context. This gives AI assistants everything they need to write code that fits your existing patterns and architecture.

📦 Available on npm

Demo

One-shot complex redesign with a vague prompt not mentioning any specific files.

https://github.com/user-attachments/assets/7eb4c39b-f069-47b5-b81a-d3d40c506f61

Limiting which files are including when fetching the codebase

Context Coder works best in small and medium-sized repositories, as it's limited to the maximum context of your LLM (in the case of Claude Sonnet/Opus 4, that's 200,000 tokens). Your whole codebase might not fit, and for this case you have two options.

Excluding Files (.cocoignore)

Create a .cocoignore file in the root of your project. This file works similarly to .gitignore, allowing you to specify files and directories that should be excluded from the command to aggregate your code - this could be test fixtures, snapshots, large test files or other secondary information that isn't useful to the LLM.

Minifying Files (.cocominify)

Create a .cocominify file in the root of your project to include files with placeholder content instead of excluding them entirely. This saves tokens while still informing the AI that the files exist and allows the AI to read them with the read_file tool if necessary. This is useful for large generated files, compiled assets, or files that don't need their full content in the AI context.

Many common build artifacts and folders are already automatically excluded (such as node_modules). The LLM can also help you with this - ask it to run the get_codebase_top_largest_files tool and suggest files that are large and/or suitable for inclusion in a .cocoignore or .cocominify file.

Combining

You can have both a .cocoignore and a .cocominify file in the same repo.

Available Tools

Available Prompts

Context Coder provides MCP prompts that help configure Claude properly for your development workflow:

To use these prompts in Claude Code:

1. Type / to open the prompt menu
2. Find "context-coder" in the list, then "Context Coder: Claude Code Setup"
3. The prompt will be inserted automatically
4. You may directly add a task after the prompt, eg /context-coder:Context Coder: Claude Code Setup (MCP) Add a new endpoint that returns a random number

To use these prompts in Claude Desktop:

Use the "plus" button just below the chat text box, the Add from <name of server>.

CLI Commands

Context Coder also provides a convenient CLI command to inspect your codebase:

List Files Command

npx context-coder ls [options]

Lists all files that will be included in the codebase analysis, showing file sizes and respecting .cocoignore and .cocominify patterns.

Options:

• --sort-by <type> - Sort by "size" or "path" (default: "size")
• -r, --reverse - Reverse sort order (ascending instead of descending)
• -d, --directory <dir> - Directory to analyze (default: current directory)
• --help - Show usage information

Examples:

npx context-coder ls                           # Default: sort by size descending
npx context-coder ls --sort-by path            # Sort alphabetically by path
npx context-coder ls -r                        # Sort by size ascending
npx context-coder ls --sort-by path --reverse  # Sort by path Z-A
npx context-coder ls -d ./src                  # Analyze specific directory

The command shows:

• Total file count and token estimates for Claude and ChatGPT
• Whether .cocoignore and .cocominify files are being used
• Formatted list of all files with sizes

Runtime Options

Context Coder supports several runtime options to modify its behavior:

npx context-coder [options]

Options:

• -m, --mini - Run in mini mode (only core tools)
• -f, --full - Run in full mode (all tools) - this is the default
• -s, --stdio - Use stdio transport instead of HTTP
• -e, --edit - Enable the edit_file tool for line-based partial edits instead of requiring complete file rewrites with write_file
• --edit-file-mode - Same as -e, --edit (legacy flag)
• -p, --port <number> - Port to listen on (default: 3001)
• -c, --claude-token-limit <number> - Set Claude token limit - useful for models with larger context windows (default: 150000)
• -g, --gpt-token-limit <number> - Set GPT token limit - useful for models with larger context windows (default: 128000)

Examples:

npx context-coder                           # Default: full mode with HTTP transport
npx context-coder -m                        # Mini mode with core tools only
npx context-coder -s                        # Use stdio transport (for Claude Code)
npx context-coder -e                        # Enable partial file editing
npx context-coder -p 8080                   # Use port 8080 instead of 3001
npx context-coder -m -s                     # Combine options for mini mode with stdio
npx context-coder -s -e -p 8080             # stdio transport with edit mode enabled and custom port

Token Limit Examples:

Context Coder helps detect when your codebase might exceed your model's context window. You can adjust these limits based on the model you're using:

# For Claude Enterprise with 500k context window
npx context-coder -c 500000

# For GPT-4 Turbo with 128k context
npx context-coder -g 128000

# For models with very large context windows
npx context-coder -c 1000000 -g 1000000

# Combine with other options
npx context-coder --edit-file-mode -c 300000 -p 8080

Model Context Window Reference:

• Claude Sonnet 3.5: ~200k tokens
• Claude Enterprise: ~500k tokens
• GPT-4: ~128k tokens
• GPT-4 Turbo: ~128k tokens
• Custom/Local Models: Varies widely

Setting appropriate token limits helps Context Coder provide better warnings when your codebase might not fit in your model's context window.

Development

npm install

npm run build
npm start  # HTTP mode
npm start -- --stdio  # stdio mode

npm run dev

Docker Variants

Context Coder provides three Docker variants:

Docker Build

./build-all.sh

# Full version
docker build -t context-coder:latest .

# Mini version
docker build --build-arg COCO_BUILD_TYPE=mini -t context-coder:mini .

# Edit version
docker build --build-arg COCO_BUILD_TYPE=edit -t context-coder:edit .

FROM ghcr.io/khromov/context-coder:full
# Add customizations

docker build -t my-coco .

Quick Start

Context Coder supports three main ways of running it:

1. Via Claude Desktop
2. Via Claude Code
3. Via other clients

Claude Desktop + npx

npx context-coder

npx context-coder --edit-file-mode

{
  "mcpServers": {
    "context-coder": {
      "command": "npx",
      "args": ["-y", "supergateway", "--streamableHttp", "http://localhost:3001/mcp"]
    }
  }
}

Claude Desktop + Docker

services:
  context-coder:
    image: ghcr.io/khromov/context-coder:full
    ports:
      - '3001:3001'
    volumes:
      - ./:/app
    working_dir: /app

services:
  context-coder:
    image: ghcr.io/khromov/context-coder:edit
    ports:
      - '3001:3001'
    volumes:
      - ./:/app
    working_dir: /app

docker-compose up

{
  "mcpServers": {
    "context-coder": {
      "command": "npx",
      "args": ["-y", "supergateway", "--streamableHttp", "http://localhost:3001/mcp"]
    }
  }
}

Claude Desktop starting prompt

Recommended setup and starting prompt: Create a Claude Project and add this to your project instructions:

Use the Context Coder MCP to edit files. Remember that partial edits are not allowed, always write out the edited files in full through the MCP. You MUST call the get_codebase_size and get_codebase MCP tools at the start of every new chat. Do not call read_file, as you already have the codebase via get_codebase - use this reference instead. ONLY call read_file if you can't find the file in your context. Do not create any artifacts unless the user asks for it, just call the write_file tool directly with the updated code. If you get cut off when writing code and the user asks you to continue, continue from the last successfully written file to not omit anything.

Use the Context Coder MCP to edit files. You have access to both edit_file (for line-based partial edits) and write_file (for complete file rewrites) tools. Use edit_file when making small, targeted changes and write_file when rewriting entire files or making extensive changes. Always use write_file if writing with edit_file fails. You MUST call the get_codebase_size and get_codebase MCP tools at the start of every new chat. Do not call read_file, as you already have the codebase via get_codebase - use this reference instead. ONLY call read_file if you can't find the file in your context. Do not create any artifacts unless the user asks for it, just call the MCP tools directly with the updated code. If you get cut off when writing code and the user asks you to continue, continue from the last successfully written file to not omit anything.

Claude Code

{
  "mcpServers": {
    "context-coder": {
      "command": "npx",
      "args": ["-y", "context-coder", "--mini", "--stdio"]
    }
  }
}

{
  "mcpServers": {
    "context-coder": {
      "command": "npx",
      "args": ["-y", "context-coder", "--mini", "--stdio", "--edit-file-mode"]
    }
  }
}

{
  "mcpServers": {
    "context-coder": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "./:/app",
        "-w",
        "/app",
        "-e",
        "COCO_MCP_TRANSPORT=stdio",
        "ghcr.io/khromov/context-coder:mini"
      ]
    }
  }
}

{
  "mcpServers": {
    "context-coder": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "supergateway", "--streamableHttp", "http://localhost:3001/mcp"]
    }
  }
}

services:
  context-coder:
    image: ghcr.io/khromov/context-coder:mini
    ports:
      - '3001:3001'
    volumes:
      - ./:/app
    working_dir: /app
    environment:
      - COCO_MCP_TRANSPORT=http
    restart: unless-stopped

You have access to both Claude Code's built-in file tools and the Context Coder MCP for enhanced codebase analysis. Follow this workflow:

1. ALWAYS start every new chat by calling get_codebase_size and get_codebase MCP tools to ingest and understand the full project context
2. Use Context Coders's codebase analysis as your primary reference - avoid reading files since you already have the complete codebase, only read file if you are missing something or if the user specifically requests it.
3. Remember: Context Coder gives you full codebase context, Claude Code gives you precise editing control - use both strategically

Configuration

volumes:
  - ./src:/app # Only expose src directory

License

MIT