MCPunk (Roaming RAG) MCP server

This MCP server enables conversation-driven code exploration by intelligently breaking files into logical chunks and providing search tools for LLMs to find specific code without using embeddings. It's designed to help you understand codebases through natural language interaction.

Installation

To get started with MCPunk, follow these steps:

1. Install uv first by following the official installation guide

2. Configure Claude Desktop:

   • Edit your claude_desktop_config.json file with the following configuration:

{
  "mcpServers": {
    "MCPunk": {
      "command": "uvx",
      "args": ["mcpunk"]
    }
  }
}

Note: If "command": "uvx" doesn't work, you may need to specify the full path, e.g., "command": "/Users/yourusername/.local/bin/uvx"

3. Restart Claude Desktop - after a short delay, the MCPunk tools should become available

Usage

Basic Workflow

1. Start a conversation by asking Claude to set up a project:

   • Example: "Hey, can you set up the ~/git/myproject and tell me how the authentication system works?"

2. Claude will then:

   • Call configure_project to index your codebase
   • Search through files and chunks to find relevant information
   • Present you with a comprehensive answer based on the code it found

Example Conversations

Exploring Code Structure

[User] Hey pal can you please set up the ~/git/mcpunk repo, then help me understand how a user of mcpunk would get the git diff of the currently checked out branch

[Claude] Call configure_project
[Claude] Call list_all_files_in_project
[Claude] Call find_files_by_chunk_content
...
[Claude] Now I understand how the git diff functionality works in mcpunk.
To get a git diff of the currently checked out branch:
1. First, configure mcpunk to work with your project
2. Use tools to see what branches were recently checked out
3. Then get the diff between the current branch (HEAD) and a reference branch

PR Review

[User] Hey pal can you please set up the ~/git/mcpunk repo and have a look at the current branch versus `scratch/1.5`

[Claude] Sets up ~/git/mcpunk and calls `diff_with_ref` for ref `scratch/1.5`

[Claude] I see you've made several changes, primarily adding a new test file `tests/test_git_analysis.py`...

Working with Multiple Codebases

You can ask Claude to set up multiple projects, allowing it to query across different repositories. This is especially useful when working with codebases that depend on each other.

Configuration Options

MCPunk can be configured via environment variables prefixed with MCPUNK_. For example:

{
  "mcpServers": {
    "MCPunk": {
      "command": "uvx",
      "args": ["mcpunk"],
      "env": {
        "MCPUNK_INCLUDE_CHARS_IN_RESPONSE": "false"
      }
    }
  }
}

For all available options, check the settings.py file in the MCPunk repository.

How MCPunk Works

MCPunk processes your codebase by:

1. Configuring a project: Points to a directory of files to analyze

2. Chunking files: Breaks files into logical segments based on their type:

   • Python files: functions, classes, imports
   • Markdown files: sections by headings
   • Vue files: template/script/style sections
   • Other files: whole file as a single chunk

3. Providing search tools: Allows Claude to:

   • Find files containing specific text
   • Locate specific chunks within files
   • View the full contents of any chunk

This approach lets the LLM intelligently navigate through your codebase, discovering exactly what it needs to answer your questions.

Limitations

• LLMs sometimes struggle with search terms (e.g., searching for "dependency" might miss "dependencies")
• Very large codebases (>1000 files) may experience performance issues
• Small projects might be better served by simply providing the entire codebase
• The LLM occasionally fails to find critical code and proceeds with incomplete context

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "MCPunk" '{"command":"uvx","args":["mcpunk"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "MCPunk": {
            "command": "uvx",
            "args": [
                "mcpunk"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "MCPunk": {
            "command": "uvx",
            "args": [
                "mcpunk"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect