mcp-codebase-index 0.2.0

Structural codebase indexer with MCP server for AI-assisted development

mcp-codebase-index

A structural codebase indexer with an MCP server for AI-assisted development. Zero runtime dependencies — uses Python's ast module for Python analysis and regex for TypeScript/JS. Requires Python 3.11+.

What It Does

Indexes codebases by parsing source files into structural metadata -- functions, classes, imports, dependency graphs, and cross-file call chains -- then exposes 17 query tools via the Model Context Protocol, enabling Claude Code and other MCP clients to navigate codebases efficiently without reading entire files.

Language Support

Language	Method	Extracts
Python (.py)	AST parsing	Functions, classes, methods, imports, dependency graph
TypeScript/JS (.ts, .tsx, .js, .jsx)	Regex-based	Functions, arrow functions, classes, interfaces, type aliases, imports
Markdown/Text (.md, .txt, .rst)	Heading detection	Sections (# headings, underlines, numbered, ALL-CAPS)
Other	Generic	Line counts only

Installation

pip install "mcp-codebase-index[mcp]"

The [mcp] extra includes the MCP server dependency. Omit it if you only need the programmatic API.

For development (from a local clone):

pip install -e ".[dev,mcp]"

MCP Server

Running

# As a console script
PROJECT_ROOT=/path/to/project mcp-codebase-index

# As a Python module
PROJECT_ROOT=/path/to/project python -m mcp_codebase_index.server

PROJECT_ROOT specifies which directory to index. Defaults to the current working directory.

Configuring with OpenClaw

Install the package on the machine where OpenClaw is running:

# Local install
pip install "mcp-codebase-index[mcp]"

# Or inside a Docker container / remote VPS
docker exec -it openclaw bash
pip install "mcp-codebase-index[mcp]"

Add the MCP server to your OpenClaw agent config (openclaw.json):

{
  "agents": {
    "list": [{
      "id": "main",
      "mcp": {
        "servers": [
          {
            "name": "codebase-index",
            "command": "mcp-codebase-index",
            "env": {
              "PROJECT_ROOT": "/path/to/project"
            }
          }
        ]
      }
    }]
  }
}

Restart OpenClaw and verify the connection:

openclaw mcp list

All 17 tools will be available to your agent.

Performance note: OpenClaw's default MCP integration via mcporter spawns a fresh server process per tool call, which means the index is rebuilt each time (~1-2s for small projects, longer for large ones). For persistent connections, use the openclaw-mcp-adapter plugin, which connects once at startup and keeps the server running:

pip install openclaw-mcp-adapter

Configuring with Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "codebase-index": {
      "command": "mcp-codebase-index",
      "env": {
        "PROJECT_ROOT": "/path/to/project"
      }
    }
  }
}

Or using the Python module directly (useful if installed in a virtualenv):

{
  "mcpServers": {
    "codebase-index": {
      "command": "/path/to/.venv/bin/python3",
      "args": ["-m", "mcp_codebase_index.server"],
      "env": {
        "PROJECT_ROOT": "/path/to/project"
      }
    }
  }
}

Available Tools (17)

Tool	Description
get_project_summary	File count, packages, top classes/functions
list_files	List indexed files with optional glob filter
get_structure_summary	Structure of a file or the whole project
get_functions	List functions with name, lines, params
get_classes	List classes with name, lines, methods, bases
get_imports	List imports with module, names, line
get_function_source	Full source of a function/method
get_class_source	Full source of a class
find_symbol	Find where a symbol is defined (file, line, type)
get_dependencies	What a symbol calls/uses
get_dependents	What calls/uses a symbol
get_change_impact	Direct + transitive dependents
get_call_chain	Shortest dependency path (BFS)
get_file_dependencies	Files imported by a given file
get_file_dependents	Files that import from a given file
search_codebase	Regex search across all files (max 100 results)
reindex	Re-index the project after file changes (MCP server only)

Programmatic Usage

from mcp_codebase_index.project_indexer import ProjectIndexer
from mcp_codebase_index.query_api import create_project_query_functions

indexer = ProjectIndexer("/path/to/project", include_patterns=["**/*.py"])
index = indexer.index()
query_funcs = create_project_query_functions(index)

# Use query functions
print(query_funcs["get_project_summary"]())
print(query_funcs["find_symbol"]("MyClass"))
print(query_funcs["get_change_impact"]("some_function"))

Development

pip install -e ".[dev,mcp]"
pytest tests/ -v
ruff check src/ tests/

References

The structural indexer was originally developed as part of the RMLPlus project, an implementation of the Recursive Language Models framework.

License

MIT