scalpel mcp — Efficient symbol level codebase retrieval…

Pitch

Description

Comments

About this project

Scalpel is a symbol-level MCP server designed for precise codebase retrieval. Instead of reading entire files, it uses get_symbol(name) to fetch just the definition span and its usages, dramatically reducing data handling and improving efficiency. Experience faster code exploration with minimal overhead.

scalpel is an innovative MCP (Minimum Cost Protocol) server designed for symbol-level codebase retrieval. Instead of retrieving an entire file, scalpel focuses on efficiency by returning only the definition span and associated usages when queried with a symbol name. This approach significantly reduces the amount of data processed, allowing for a more streamlined and precise retrieval of information.

With scalpel, users can quickly index various programming language repositories, including TypeScript, Python, and Go.

Key Features

Optimized Retrieval: The get_symbol(name) function ensures that only relevant data is read, dramatically lowering token usage—in one case reducing it by 90%.
High Accuracy: Scalpel matches or exceeds the accuracy of leading competitors in retrieving definitions and usages without the drawbacks of text matching methods, providing reliable results for developers.

Usage Example

To get started with scalpel, the following commands illustrate basic usage:

# Install the package globally
npm install -g @amritessh/scalpel

# Index a repository (choose language: ts, python, go; default is ts)
scalpel-index /path/to/repo /path/to/repo/.scalpel/index.db [lang]

# Run the MCP server over standard input/output
scalpel /path/to/repo /path/to/repo/.scalpel/index.db

Users can connect an MCP client easily and utilize scalpel's capabilities in their workflows. An example command for the Claude Code environment might look like:

claude mcp add scalpel -- scalpel /path/to/repo /path/to/repo/.scalpel/index.db

Performance Comparison

Scalpel has been benchmarked against real-world competitors, demonstrating superior performance in both cost and accuracy. Below is a summary of its results compared to similar tools:

Tool	Definition-only Cost	Definition Accuracy	Usage Lookup Cost	Usage Accuracy
grep	6,783 tokens	100%	29,898 tokens	60%
jcodemunch-mcp	2,723 tokens	82%	—	—
Serena (LSP)	2,386 tokens	100%	~245–250K tokens	—
scalpel	1,732 tokens	100%	3,126 tokens	100%

Research Background

The development of scalpel stems from a comprehensive research study focused on symbol-level code retrieval for AI coding agents, measured by token costs and completion effects. The results showcase scalpel's capability to serve as a cost-effective and precise tool for coding tasks, especially in scenarios that demand accuracy and efficiency.

This repository represents the maintained and installable version of scalpel, which is continually developed separately from the original research artifacts.