Codebase Patterns MCP

代码库模式MCP服务器

MCP服务器，为Claude Code提供对团队代码库模式的语义访问，因此生成的代码从第一天起就遵循您的内部标准。

问题

当您要求Claude“添加遥测跟踪”时，它会生成指向以下内容的通用代码 localhost 没有合规字段。您的团队已经拥有一个内部遥测库，其中包含特定的端点、必填字段和约定。克劳德对此一无所知。

解决方案

此MCP服务器为您的存储库建立索引，并公开 search_code 工具。当Claude需要为常见问题（身份验证、遥测、数据库、HTTP客户端）编写代码时，它会首先搜索您的代码库，并生成符合您团队实际模式的代码。

相同的提示，完全不同的输出：

搜索质量

针对遥测、身份验证、HTTP客户端、数据库存储库和错误处理中的8个地面实况查询进行了评估：

每个查询都会在排名1处找到一个相关结果。所有预期结果都出现在前5名之内。

主要特点

• 语义代码搜索 --按含义而不是关键字查找代码
• 多语言支持 --Go、Java、Python、JavaScript、TypeScript
• 模式检测 --工厂、单例、构建器、策略、装饰器、观察者、存储库
• 框架检测 --Spring Boot、Flask、Express、NestJS、Django、FastAPI等
• 功能级别索引 --每个函数都有丰富的元数据索引
• 请求日志记录 --每个MCP工具调用的结构化JSONL日志
• 评估框架 --地面实况查询、指标和自动报告

快速开始

# 1. Clone and setup
git clone https://github.com/Manojred22/codebase-patterns-mcp.git
cd codebase-patterns-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 2. Configure
cp .env.template .env
# Edit .env and add your OPENAI_API_KEY

# 3. Add your repositories to ./repos/

# 4. Index your code
python index_repos.py

# 5. Test the search
python search_cli.py "authentication handler"

# 6. Configure MCP server for Claude Code
cp .mcp.json.template .mcp.json
# Edit .mcp.json with your absolute paths

有关详细的分步说明，请参阅 docs/setup-guide.md.

尝试演示

使用附带的示例仓库运行完整演示（Acme品牌代码，跨5种语言）：

bash demo/setup_demo.sh

这将复制示例存储库，对其进行索引，运行eval，并显示演示之前/之后的内容。您将看到：

1. 场景1 --Claude的通用输出（Jaeger、localhost、无合规性）
2. 场景2 --带有实际源代码的实时MCP搜索结果
3. 场景3 --Claude使用团队模式（内部端点、合规性字段）的输出

要运行单个步骤，请执行以下操作：

# Just the eval (after indexing)
python eval/run_eval.py

# Just the demo
python eval/demo.py

# Check tool routing after running prompts through Claude Code
python -c "from eval.tool_routing import generate_routing_checklist; print(generate_routing_checklist())"

结果保存到 data/eval/report.md 和 data/eval/results.json.

建筑

Your Repos → Indexer (tree-sitter) → Embeddings (OpenAI) → Vector DB (Chroma) → MCP Server → Claude Code

让克劳德主动使用你的模式

默认情况下，Claude仅在您明确询问时进行搜索。成功 在生成新代码之前自动检查内部代码:

1. 复制 CLAUDE.md.template 到您的项目根目录 CLAUDE.md
2. 根据您的项目特定规则进行自定义

这篇文章告诉Claude在为常见问题编写代码之前搜索团队的代码库，因此它使用您的内部库，而不是通用的替代品。

在自己的代码库上衡量效率

一旦你在一个真实的项目中使用了MCP服务器，以下是如何衡量它是否真的有帮助。

记录的内容

每 search_code 通话记录到 data/logs/mcp-requests-YYYY-MM-DD.jsonl.每个条目记录：

{
  "timestamp": "2026-02-18T15:01:22Z",
  "tool_name": "search_code",
  "query": "authentication middleware",
  "filters": {"language": "go"},
  "limit": 5,
  "result_count": 5,
  "latency_ms": 142.3,
  "error": null
}

这为您提供了克劳德搜索内容和发现内容的完整审计跟踪。

对你的代码进行评估

写下你自己的基本事实查询 eval/ground_truth.py --使用您期望找到的函数ID查询对您的团队很重要。然后运行：

python eval/run_eval.py

这产生 data/eval/report.md 随着Recall@K, Precision@K，以及MRR分数，再加上每个查询的细分，准确显示找到了哪些结果，错过了哪些结果。

检查代码质量

Claude使用MCP结果生成代码后，检查它是否符合您的模式：

from eval.code_quality import check_code_quality

result = check_code_quality(generated_code, "telemetry")
print(result)
# {'score': 1.0, 'acme_markers_found': ['AcmeTracerConfig', 'TeamLabel'], 'generic_markers_found': [], 'verdict': 'conformant'}

在中编辑标记列表 eval/code_quality.py 以匹配您团队的标识符，而不是Acme默认值。

验证刀具路径

检查克劳德是否在打电话 search_code 当它应该（而不是在它不应该的时候调用它）：

python -c "from eval.tool_routing import generate_routing_checklist; print(generate_routing_checklist())"

这将读取JSONL日志并生成通过/失败检查表。在中编辑提示列表 eval/tool_routing.py 与团队的共同任务相匹配。

随着时间的推移要跟踪什么

添加自己的地面真相

替换中的示例查询 eval/ground_truth.py 与您的代码库相关的查询：

TestQuery(
    id="your-auth",
    query="JWT token validation middleware",
    category="auth",
    expected_ids=[
        "your-repo/src/auth/middleware.go:ValidateJWT",
        "your-repo/src/auth/token.go:ParseToken",
    ],
    expected_id_patterns=[
        r"your-repo.*auth.*:ValidateJWT",
        r"your-repo.*auth.*:ParseToken",
    ],
)

跑 python eval/run_eval.py 索引以查看实际函数ID后，更新 expected_ids 为了匹配。

项目结构

src/                     # Core server and indexing
  mcp_server.py          # MCP JSON-RPC server (search_code + get_stats tools)
  request_logger.py      # Structured JSONL request logging
  indexer.py             # Multi-language code indexer
  embeddings.py          # OpenAI embedding generator
  vector_store.py        # ChromaDB vector store
  parsers/               # Tree-sitter parsers (Go, Java, Python, JS, TS)
  detectors/             # Pattern and framework detection

eval/                    # Evaluation framework
  ground_truth.py        # 8 test queries with expected results
  search_quality.py      # Recall@K, Precision@K, MRR metrics
  run_eval.py            # Main eval runner
  report.py              # Markdown report generator
  demo.py                # Before/after demo for presentations
  tool_routing.py        # Tool routing verification checklist
  code_quality.py        # Pattern conformance checker

sample-repos/            # Acme-branded sample code (5 languages, 27 files)
demo/setup_demo.sh       # One-command demo setup

需求

• Python 3.9+
• OpenAI API密钥
• 支持的语言：Go、Java、Python、JavaScript、TypeScript

成本

索引成本取决于代码库大小：

• 约2000个函数：约0.04美元（使用 text-embedding-3-small)
• 仅当代码发生重大更改时才需要重新索引

贡献

向医生提出公关，解释你想做什么。