Code Navigation MCP Server

Reduce Claude Code token usage by 95-99% for code navigation tasks!

A generic MCP server for efficient code navigation across any repository (Linux kernel, libcamera, your projects, etc.) without reading full files.

🚀 Quick Start

# 1. Clone the repo
git clone https://github.com/Balki01/code-nav-mcp.git
cd code-nav-mcp

# 2. Run installer
./install.sh

# 3. Add to Claude Code .mcp.json
# See Installation section below

Features

• Symbol Lookup: Find function/struct/macro definitions instantly (ctags-based)
• Cross-References: Find all usages of a symbol (ripgrep-based)
• Caller Analysis: See who calls a function
• Git Integration: Blame functions, show commit history
• Multi-Repo: Index and search multiple repos simultaneously
• Smart Grep: Structured grep output without full file reads

Installation

1. Install Dependencies

# Python MCP SDK
pip install mcp

# System tools (if not already installed)
sudo apt install universal-ctags ripgrep

2. Make Server Executable

chmod +x server.py

3. Configure Claude Code

Option A: Project-level (Recommended)

Create .mcp.json in your project root:

{
  "mcpServers": {
    "code-nav": {
      "command": "/absolute/path/to/code-nav-mcp/run_server.sh"
    }
  }
}

Option B: Global settings

Add to ~/.claude/settings.json - NOT RECOMMENDED, see MCP configuration docs

4. Restart Claude Code

After adding the MCP server configuration, restart Claude Code to load the new server.

Usage Examples

1. Index Your Repositories

First, add and index the repos you want to navigate:

# Add Linux kernel
add_repo(name="linux", path="/home/administrator/SRC/linux", branch="balki/isc-6.18-fixes")

# Add libcamera
add_repo(name="libcamera", path="/work5/balki/SRC_BUILD/libcamera", branch="mchp-next-v2-v0.6.0")

Indexing takes 30-60 seconds for large repos like the kernel (one-time cost).

2. Find Function Definitions

find_symbol(symbol="isc_awb_work", kind="function")

Output:

Found 1 definition(s) for 'isc_awb_work':

[linux] drivers/media/platform/microchip/microchip-isc-base.c:1503
  Kind: function
  Code: static void isc_awb_work(struct work_struct *w)

Token savings: Instead of reading 2000+ line file, you get just the location!

3. Find All References

find_references(symbol="V4L2_CID_AUTO_WHITE_BALANCE", repo="linux")

Returns all locations where the symbol is used with surrounding context.

4. Find Who Calls a Function

find_callers(function="isc_update_awb_ctrls", repo="linux")

Shows all call sites without reading full files.

5. Git Blame a Function

git_blame_function(function="isc_s_awb_ctrl", repo="linux")

Shows who last modified the function and when.

6. Show Commit History

git_show_symbol(symbol="isc_awb_work", repo="linux")

Shows recent commits that touched this symbol.

7. Smart Grep

smart_grep(pattern="V4L2_CTRL_FLAG_INACTIVE", file_type="c", repo="linux", context=3)

Structured grep with file:line:content output.

Workflow Example: Debugging AWB Issue

Traditional approach (high token usage):

1. Read entire microchip-isc-base.c (2000+ lines)
2. Read header files
3. Re-read after each discovery
4. Total: ~10,000+ lines = ~100K tokens

With Code Nav MCP (low token usage):

1. find_symbol("isc_s_awb_ctrl", kind="function")
   → drivers/media/platform/microchip/microchip-isc-base.c:1706

2. find_references("V4L2_CTRL_FLAG_INACTIVE", repo="linux")
   → Shows all checks with context

3. find_callers("isc_update_awb_ctrls")
   → See who calls this function

4. git_blame_function("isc_s_awb_ctrl", repo="linux")
   → Who last changed it

Total: ~400 lines read, 95% token savings!

Tips for Maximum Efficiency

1. Index repos once - Indexing is a one-time cost
2. Use find_symbol first - Get exact locations before reading
3. Use repo parameter - Narrow searches to specific repos
4. Combine with Claude's Read tool - After finding the location, read just that function:

   find_symbol("isc_awb_work")
   → Found at line 1503
   
   Read microchip-isc-base.c lines 1503-1600
   

Symbol Kinds

When using find_symbol, you can filter by kind:

• function - Function definitions
• struct - Struct definitions
• macro - #define macros
• variable - Global variables
• typedef - Type definitions
• member - Struct/class members

Performance

• Indexing: 30-120 seconds per repo (one-time)
• Symbol lookup: <100ms (instant)
• References: 1-5 seconds (depends on repo size)
• Git operations: <1 second

Troubleshooting

"ctags not found"

sudo apt install universal-ctags
# NOT 'exuberant-ctags' - that's outdated

"Repository not indexed"

# Re-run indexing
add_repo(name="linux", path="/home/administrator/SRC/linux")

"ripgrep not found"

sudo apt install ripgrep

Architecture

• ctags: Generates symbol index (definitions)
• ripgrep: Fast full-text search (references)
• git: History and blame integration
• MCP: Exposes tools to Claude Code

The server maintains in-memory repo registry and delegates to command-line tools for actual work.

📊 Real-World Impact

Created while debugging Linux kernel camera drivers (microchip-isc). Typical investigation that would use 750K-1.5M tokens now uses 7.5K-15K tokens.

From the creator:

"I was spending hundreds of thousands of tokens just finding where functions were defined in the kernel. This tool paid for itself in a single debugging session."

🛣️ Roadmap

• Cscope integration for call graphs
• Semantic search with embeddings
• Cache frequently accessed symbols
• Support for LSP integration
• Cross-repo symbol resolution

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

🐛 Issues & Support

• Report bugs
• Request features
• Ask questions

📜 License

MIT - See LICENSE file for details.

🙏 Acknowledgments

Built for developers debugging complex codebases. Inspired by real-world kernel development workflows.