MCP Codebase Search

@技术/mcp代码库搜索

使用模型上下文协议（MCP）的代码库的本地第一语义搜索系统

📋 目录

• 概述
• 版本历史
• 特性
• 安装
• 快速开始
• 用法
• 配置
• MCP客户端配置
• 支持的语言
• 建筑
• 故障排除
• 发展
• 贡献
• 许可证

概述

Codebase Memory MCP Server使LLM编码助手能够可靠地发现代码库中的现有代码，防止重复实现和错误的文件编辑。它使用本地嵌入、Tree sitter感知分块和LanceDB进行矢量存储——所有这些都在本地运行，不依赖于云。

版本历史

当前版本： 0.1.16

• 0.1.16 -刷新的重新扫描日志记录的版本升级和文件可见性下降
• 0.1.15 -更新后的MCP工具界面和服务器横幅的版本升级
• 0.1.14 -针对MCP服务器、包清单和变更日志的过时索引检测和版本同步的Bug修复版本发布
• 0.1.13 -指数新鲜度和 update_codebase_scan 改进
• 0.1.12 -停滞警告和扩展的MCP工具表面

有关完整的发行说明，请参阅 更改日志.md.

为什么使用这个？

• 防止重复代码：人工智能助手可以在创建新的实现之前找到现有的实现
• 精确的代码导航：语义搜索理解代码含义，而不仅仅是关键字
• 隐私第一：所有处理都在本地进行——你的代码永远不会离开你的机器
• 快速高效：通过智能缓存优化快速搜索响应
• 多语言：支持TypeScript、JavaScript、Python、Java、C#、Svelte、HTML、CSS、Markdown等
• 智能过滤：从搜索结果中排除测试文件和库代码
• 稳定性检测：索引可能过期时自动发出警告

特性

• 🔒 本地优先：所有操作都在本地运行，没有外部API调用
• 🔍 语义搜索：按含义查找代码，而不仅仅是关键字
• 🌳 树保姆解析：AST感知代码分块以获得有意义的结果
• 🤖 MCP集成：与MCP兼容的AI助手（Claude、Kiro等）无缝集成
• 🌐 多语言支持：TypeScript、JavaScript、Python、Java、C#、Svelte、HTML、CSS、YAML、Markdown
• 🖥️ Web管理UI：通过浏览器界面管理索引代码库
• ⚡ 性能优化：具有智能结果缓存的快速搜索响应
• 🎯 智能过滤：从结果中排除测试文件和库代码
• 📊 详细统计：跟踪块计数、文件计数、语言分布和扫描时间
• 🔄 增量重新扫描：基于哈希的更改检测--仅重新索引修改过的文件
• 🚫 锁定文件排除：自动排除 package-lock.json, yarn.lock，以及其他锁定文件
• ⚠️ 稳定性警告：当索引超过10分钟时，搜索结果包括警告

安装

全局安装（推荐）

npm install -g @teknologika/mcp-codebase-search

这使得三个命令在全球范围内可用：

• mcp-codebase-search --用于AI助手的MCP服务器
• mcp-codebase-ingest --用于索引代码库的CLI
• mcp-codebase-manager --用于管理的Web UI

本地安装

npm install @teknologika/mcp-codebase-search

然后与一起使用 npx:

npx mcp-codebase-ingest --path ./my-project --name my-project
npx mcp-codebase-search
npx mcp-codebase-manager

需求

• Node.js：22.0.0或更高
• npm：10.0.0或更高版本
• 磁盘空间：约500MB用于嵌入模型（首次使用时下载）

快速开始

1.为你的第一个代码库建立索引

mcp-codebase-ingest --path ./my-project --name my-project

输出示例：

Ingesting codebase: my-project
Path: /Users/dev/projects/my-project

Scanning directory...
Parsing files...
Generating embeddings...
Storing chunks...

✓ Ingestion completed successfully!

  Total files scanned: 256
  Supported files: 253
  Chunks created: 2,022
  Duration: 29.7s

Languages detected:
  typescript: 1,800 chunks (200 files)
  javascript: 150 chunks (40 files)
  markdown: 72 chunks (13 files)

2.配置您的MCP客户端

适用于克劳德桌面

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "codebase-search": {
      "command": "mcp-codebase-search",
      "args": []
    }
  }
}

3.设置您的代理.md

添加一个 AGENTS.md 将文件添加到您的项目中，以指示AI助手在创建新代码之前使用代码库搜索工具：

# AGENTS.md — Codebase Dedupe Protocol

## Goal
Prevent duplicate implementations and "wrong file" edits by making **codebase-search** the *only valid source* for claims about what already exists in this repo during this session.

## Tools you MUST use for codebase discovery
- `list_codebases`
- `search_codebases`
- `get_codebase_stats`
- `get_chunk_content`
- `get_file_content`
- `get_adjacent_chunks`
- `list_files`
- `update_codebase_scan`

After updates run `update_codebase_scan` to refresh the index.

## Hard rule: No creation without a Dedupe Ticket
Before adding a new file, module, class, function, or helper, produce a Dedupe Ticket:

**Dedupe Ticket**
- Intent signature: ``
- Queries: ``
- Top matches: ``
- Decision: `reuse | extend | new`
- Rationale: ``

## Graceful degradation
If the MCP server is unavailable: state **DEGRADED MODE** and stop before making changes.

4.开始在您的AI助手中使用

配置后，您的AI助手可以使用这些工具：

• list_colowers --查看所有具有扫描时间的索引代码库
• 搜索_折扣 --带有过时警告的语义搜索
• get_coordinate_stats --代码库的详细统计信息
• get_chunk_content --按行范围检索特定代码块
• 获取_文件_内容 --检索完整的文件内容
• get_adjacent_chunks --检索块的周围上下文
• 列表文件 --列出代码库中的所有索引文件
• 更新_降级_扫描 --代码更改后逐步刷新索引
• 开放式贬值管理器 --代表您在浏览器中启动Manager UI

5.（可选）浏览管理器UI

mcp-codebase-manager

开启 http://localhost:8008 在默认浏览器中，使用可视化界面：

• 使用过滤器搜索代码库
• 管理索引代码库
• 查看统计信息和文件级详细信息
• 添加具有实时进度跟踪功能的新代码库
• 重新扫描更改

用法

摄入CLI

这 mcp-codebase-ingest 命令为语义搜索的代码库建立索引。

基本用法

mcp-codebase-ingest --path  --name 

选项

示例

# Index a local project
mcp-codebase-ingest --path ~/projects/my-app --name my-app

# Index with custom config
mcp-codebase-ingest --path ./backend --name backend-api --config ./custom-config.json

# Index without gitignore filtering
mcp-codebase-ingest --path ./my-project --name my-project --no-gitignore

# Re-index an existing codebase (old data is automatically replaced)
mcp-codebase-ingest --path ~/projects/my-app --name my-app

什么会被索引？

• ✅ TypeScript、JavaScript、Python、Java、C#、Svelte、HTML、CSS、YAML、JSON、Markdown
• ✅ 嵌套子目录中的文件（递归扫描）
• ✅ 语义代码块（函数、类、方法、接口）
• ✅ 元数据标签（测试文件、库文件）
• ❌ 大于1MB的文件（可配置）
• ❌ 文件在 .gitignore （默认情况下）
• ❌ 锁定文件(package-lock.json, yarn.lock, pnpm-lock.yaml等等）
• ❌ 隐藏目录（以开头 .)
• ❌ 构建输出(node_modules, dist, build, target等等）

MCP服务器

MCP服务器为AI助手提供了搜索和探索代码库的工具。

启动服务器

mcp-codebase-search

服务器在stdio模式下运行，并通过标准输入/输出与MCP客户端通信。

可用工具

list_codebases

列出所有带有元数据（包括扫描时间）的索引代码库。

输入： 无

输出：

{
  "codebases": [
    {
      "name": "my-project",
      "path": "/path/to/project",
      "chunkCount": 2022,
      "fileCount": 253,
      "lastIngested": "2026-03-21T06:18:24Z",
      "lastModified": "2026-03-21T06:18:24Z",
      "lastScanAge": 57,
      "lastRescanChangedAt": "2026-03-21T06:18:24Z",
      "lastRescanFilesChanged": 4,
      "lastRescanFilesAdded": 1,
      "lastRescanFilesModified": 2,
      "lastRescanFilesDeleted": 1,
      "lastRescanChangedFilePaths": ["src/a.ts", "src/b.ts"],
      "languages": ["typescript", "javascript", "markdown"],
      "status": "active"
    }
  ]
}

lastScanAge 是上次扫描后的秒数。 lastRescan* 字段总结了最近有意义的刷新。用它们来决定是否打电话 update_codebase_scan 在搜索之前。

search_codebases

跨索引代码库执行语义搜索。

输入：

{
  "query": "authentication function",
  "codebaseName": "my-project",
  "language": "typescript",
  "maxResults": 10,
  "includeContent": false,
  "topContentResults": 3
}

除以下字段外的所有字段 query 是可选的。集 includeContent: true 在每个结果中包含完整的源代码，或使用 topContentResults 仅包含最佳匹配的完整源代码。

输出：

{
  "results": [
    {
      "filePath": "src/auth/authenticate.ts",
      "startLine": 15,
      "endLine": 45,
      "language": "typescript",
      "chunkType": "function",
      "similarityScore": 0.92
    }
  ],
  "totalResults": 1,
  "queryTime": 45,
  "staleWarning": "Index is 47 minutes old. Call update_codebase_scan('my-project') to refresh."
}

staleWarning 当索引超过10分钟时出现。默认情况下，内容被排除在外，但 includeContent 和 topContentResults 可以将其包含在搜索响应中。

get_chunk_content

按文件路径和行范围检索特定块的源代码。

输入：

{
  "codebaseName": "my-project",
  "filePath": "src/auth/authenticate.ts",
  "startLine": 15,
  "endLine": 45
}

输出：

{
  "codebaseName": "my-project",
  "filePath": "src/auth/authenticate.ts",
  "startLine": 15,
  "endLine": 45,
  "language": "typescript",
  "chunkType": "function",
  "content": "export async function authenticate(...) { ... }",
  "lineNumberDrift": 0
}

lineNumberDrift 当在偏移的行范围内发现块时，该值为非零——这可能会在代码移动的增量重新扫描后发生。当没有找到精确匹配时，会自动使用模糊±5行搜索。

get_file_content

检索索引文件的完整内容。

输入：

{
  "codebaseName": "my-project",
  "filePath": "src/auth/authenticate.ts"
}

输出：

{
  "codebaseName": "my-project",
  "filePath": "src/auth/authenticate.ts",
  "language": "typescript",
  "content": "// full file content...",
  "chunkCount": 8,
  "totalLines": 245
}

get_adjacent_chunks

检索文件中特定块之前和之后的块。当搜索结果具有分割块类型时，使用此选项，如 method_part_2 或 class_part_5 您需要周围的上下文，而无需获取整个文件。

输入：

{
  "codebaseName": "my-project",
  "filePath": "src/auth/authenticate.ts",
  "startLine": 15,
  "endLine": 45,
  "before": 1,
  "after": 1
}

输出：

{
  "before": [
    {
      "startLine": 1,
      "endLine": 14,
      "chunkType": "function",
      "content": "..."
    }
  ],
  "reference": {
    "startLine": 15,
    "endLine": 45,
    "chunkType": "method"
  },
  "after": [
    {
      "startLine": 46,
      "endLine": 60,
      "chunkType": "method",
      "content": "..."
    }
  ]
}

list_files

列出包含元数据的代码库中的所有索引文件。

输入：

{
  "codebaseName": "my-project"
}

输出：

{
  "files": [
    {
      "filePath": "src/auth/authenticate.ts",
      "language": "typescript",
      "chunkCount": 8,
      "lastIngestion": "2026-03-21T06:18:24Z",
      "sizeBytes": 4521,
      "isTestFile": false,
      "isLibraryFile": false,
      "fileHash": "a1b2c3d4..."
    }
  ],
  "codebaseName": "my-project",
  "totalFiles": 253
}

get_codebase_stats

检索特定代码库的详细统计信息。

输入：

{
  "name": "my-project"
}

输出：

{
  "name": "my-project",
  "path": "/path/to/project",
  "chunkCount": 2022,
  "fileCount": 253,
  "lastIngestion": "2026-03-21T06:18:24Z",
  "languages": [
    { "language": "typescript", "fileCount": 200, "chunkCount": 1800 }
  ],
  "chunkTypes": [
    { "type": "function", "count": 800 },
    { "type": "method", "count": 1022 }
  ],
  "sizeBytes": 1250000
}

update_codebase_scan

通过扫描更改的文件来逐步刷新索引。仅对内容已更改的文件重新索引，未更改的文件将被跳过。扫描成功后，搜索缓存会自动清除。

输入：

{
  "name": "my-project",
  "verbose": false
}

集 verbose: true 在响应中包含添加、修改和删除的文件路径列表。

回应还包括 filesIndexed，报告扫描后索引中存在多少个唯一文件，以及 filesDropped，突出显示了扫描的支持文件和实际进入索引的文件之间的差距。

输出：

{
  "name": "my-project",
  "filesScanned": 253,
  "filesAdded": 2,
  "filesModified": 5,
  "filesDeleted": 1,
  "filesUnchanged": 245,
  "filesIndexed": 250,
  "filesDropped": 3,
  "chunksAdded": 18,
  "chunksDeleted": 12,
  "durationMs": 644,
  "cacheCleared": true,
  "message": "Successfully refreshed codebase 'my-project': 2 added, 5 modified, 1 deleted, 245 unchanged, 250 indexed"
}

open_codebase_manager

在默认浏览器中打开基于web的管理器UI。如果管理器服务器尚未运行，则自动启动它。

输入： 无

输出：

{
  "url": "http://localhost:8008",
  "message": "Opening codebase manager at http://localhost:8008",
  "serverStarted": true
}

管理器UI

Manager UI提供了一个基于浏览器的界面，用于管理索引代码库。

启动管理器

mcp-codebase-manager

开启 http://localhost:8008 自动。

特性

搜索选项卡：

• 跨所有索引代码库的语义搜索
• 按代码库和最大结果筛选
• 排除测试文件和库文件
• 带有颜色编码置信度评分的可折叠结果：

- 🟢 绿色（0.80–1.00）：非常匹配 - 🟡 黄色（0.60–0.79）：匹配良好 - 🔵 蓝色（0.00–0.59）：较低匹配

管理选项卡：

• 查看所有带有块计数和上次扫描日期的索引代码库
• 使用文件夹浏览器和实时进度跟踪添加新代码库
• 重新扫描代码库以进行增量更新
• 查看每个文件的详细信息并从索引中删除单个文件
• 重命名和删除代码库
• 亮/暗主题切换

经理控制：

• 退出按钮优雅地停止服务器并关闭浏览器选项卡

配置

配置存储在 ~/.codebase-memory/config.json.

配置文件示例

{
  "lancedb": {
    "persistPath": "~/.codebase-memory/lancedb"
  },
  "embedding": {
    "modelName": "Xenova/all-MiniLM-L6-v2",
    "cachePath": "~/.codebase-memory/models"
  },
  "server": {
    "port": 8008,
    "host": "localhost",
    "sessionSecret": "change-me-in-production"
  },
  "mcp": {
    "transport": "stdio"
  },
  "ingestion": {
    "batchSize": 100,
    "maxFileSize": 1048576,
    "maxChunkTokens": 512,
    "chunkOverlapTokens": 50,
    "storeFullFiles": true
  },
  "search": {
    "defaultMaxResults": 50,
    "cacheTimeoutSeconds": 60
  },
  "logging": {
    "level": "info"
  },
  "schemaVersion": "1.0.0"
}

配置选项

MCP客户端配置

克劳德桌面版

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "codebase-search": {
      "command": "mcp-codebase-search",
      "args": []
    }
  }
}

其他MCP客户端

{
  "mcpServers": {
    "codebase-search": {
      "command": "mcp-codebase-search",
      "args": [],
      "env": {
        "CONFIG_PATH": "~/.codebase-memory/config.json",
        "LOG_LEVEL": "info"
      }
    }
  }
}

验证配置

1. 重新启动客户端应用程序
2. 检查一下 codebase-search 出现在MCP服务器列表中
3. 呼叫 list_codebases 验证连接

支持的语言

不产生AST块的文件（例如仅配置或仅导入文件）被索引为单个文件级块，因此它们仍然可以搜索。

建筑

系统概述

┌─────────────────────────────────────────────────────────────┐
│                     Entry Points                             │
├──────────────┬──────────────────┬──────────────────────────┤
│  MCP Server  │  Ingestion CLI   │     Manager UI           │
│  (stdio)     │  (command-line)  │  (Fastify + Handlebars)  │
└──────┬───────┴────────┬─────────┴──────────┬───────────────┘
       │                │                    │
┌──────▼────────────────▼────────────────────▼───────────────┐
│                   Core Services                             │
├─────────────┬──────────────┬──────────────┬────────────────┤
│  Codebase   │    Search    │  Ingestion   │   Embedding    │
│  Service    │   Service    │   Service    │    Service     │
└──────┬──────┴──────┬───────┴──────┬───────┴────────┬───────┘
       │             │              │                │
┌──────▼─────────────▼──────────────▼────────────────▼───────┐
│                   Storage & Parsing                         │
├──────────────┬──────────────────┬─────────────────────────┤
│   LanceDB    │  Tree-sitter     │  Hugging Face           │
│ (Vector DB)  │  (Code Parsing)  │  (Embeddings, local)    │
└──────────────┴──────────────────┴─────────────────────────┘

数据流

摄入

Source Code → File Scanner → Tree-sitter Parser → Semantic Chunks
                                                         ↓
                                                  Token Counter
                                                         ↓
                                              Split Oversized Chunks
                                                         ↓
                                                 File Classifier
                                                         ↓
LanceDB ← Embeddings ← Embedding Service ← Tagged Chunks

分块策略： 树保姆提取语义单元（函数、类、方法）。超过512个标记的单位在具有50个标记重叠的行边界上分割。产生零AST块的文件会得到一个文件级块，以确保所有内容都是可搜索的。

搜索

Query → Embedding Service → Vector
                              ↓
                         LanceDB Search (top N×10 candidates)
                              ↓
                         Name/Symbol Boost (re-rank)
                              ↓
                         Apply Filters → Trim to N → Response

每次搜索后，搜索缓存都会自动清除 update_codebase_scan.

存储模式

LanceDB表命名： codebase_{name}_{schemaVersion} （例如。 codebase_my-project_1_0_0)

行结构：

{
  "id": "my-project_2026-03-21T06:18:24Z_0",
  "vector": [0.1, 0.2, "..."],
  "content": "export async function authenticate(...) { ... }",
  "filePath": "src/auth.ts",
  "startLine": 15,
  "endLine": 45,
  "language": "typescript",
  "chunkType": "function",
  "isTestFile": false,
  "isLibraryFile": false,
  "fileHash": "a1b2c3d4...",
  "fullFileContent": "// complete file content",
  "ingestionTimestamp": "2026-03-21T06:18:24Z",
  "_codebaseName": "my-project",
  "_path": "/path/to/project",
  "_lastIngestion": "2026-03-21T06:18:24Z"
}

故障排除

常见问题

“找不到命令：mcp代码库搜索”

npm install -g @teknologika/mcp-codebase-search
# or use npx
npx mcp-codebase-search

“初始化LanceDB失败”

# Check permissions
ls -la ~/.codebase-memory/lancedb

# Reset LanceDB (WARNING: deletes all indexed data)
rm -rf ~/.codebase-memory/lancedb

# Re-ingest
mcp-codebase-ingest --path ./my-project --name my-project

“嵌入模型下载失败”

# Check available disk space (~500MB needed)
df -h ~/.codebase-memory

# Clear model cache and retry
rm -rf ~/.codebase-memory/models
mcp-codebase-ingest --path ./my-project --name my-project

“搜索未返回任何结果”

语义搜索最适合描述性短语，而不是精确的标识符。尝试更广泛的查询：

# Instead of: "validateEmailAddress"
# Try: "email validation function"

要进行精确的标识符查找，请使用 get_file_content 经过广泛搜索后，最有可能的文件。

“管理器UI无法打开/端口正在使用中”

# Check what's using port 8008
lsof -i :8008

# Use a different port in config
# ~/.codebase-memory/config.json
{ "server": { "port": 8009 } }

代码更改后索引已过时

呼叫 update_codebase_scan 经过重大编辑。文件哈希意味着只有修改过的文件才会被重新嵌入，因此即使在大型代码库上，重新扫描也很快。

性能提示

• 增加批量大小 为了更快的初始摄取（需要更多的RAM）：

  { "ingestion": { "batchSize": 200 } }

• 使用SSD存储 对于LanceDB持久性目录
• 排除不必要的文件 通过 .gitignore
• 定期重新扫描 --呼叫 update_codebase_scan 发生重大变化后

发展

设置

git clone https://github.com/teknologika/mcp-codebase-search.git
cd mcp-codebase-search
npm install
npm run build

脚本

npm run build          # Compile TypeScript + copy UI assets
npm test               # Run all tests
npm run test:watch     # Watch mode
npm run test:coverage  # Coverage report
npm run lint           # ESLint
npm run lint:fix       # Auto-fix lint issues
npm run clean          # Remove build artifacts
npm run typecheck      # Type check without building

项目结构

src/
├── bin/                    # Entry points (mcp-server, ingest, manager)
├── domains/                # Domain business logic
│   ├── codebase/           # Codebase CRUD and file operations
│   ├── search/             # Semantic search with caching
│   ├── ingestion/          # File scanning and indexing pipeline
│   ├── embedding/          # Local embedding generation
│   └── parsing/            # Tree-sitter + plaintext fallback parsers
├── infrastructure/         # External integrations
│   ├── lancedb/            # LanceDB client wrapper
│   ├── mcp/                # MCP server and tool schemas
│   └── fastify/            # Manager UI server and routes
├── shared/                 # Shared utilities
│   ├── config/             # Configuration management
│   ├── logging/            # Structured logging (Pino)
│   ├── types/              # Shared TypeScript types
│   └── utils/              # File hashing, token counting, classification
└── ui/                     # Web interface
    └── manager/
        ├── templates/      # Handlebars templates
        └── static/         # CSS and JavaScript

贡献

报告问题

1. 搜索现有问题以避免重复
2. 包括：Node.js版本、操作系统、复制步骤、错误消息

提交拉取请求

1. 分叉并创建特征分支： git checkout -b feature/my-feature
2. 进行更改、添加测试、更新文档
3. 跑 npm test 和 npm run lint
4. 承诺与 约定式提交: feat:, fix:, docs:等等。
5. 打开拉取请求

贡献领域

• 🌐 语言支持 --其他树型语法（Rust、Go、Ruby）
• 🔍 搜索改进 --FTS/关键字搜索模式，用于精确查找标识符
• ⚡ 演出 --搜索和摄取优化
• 🎨 UI 改进 --管理器UI增强功能
• 🐛 错误修复 --查看未决问题

安全

• 没有外部API调用 --所有处理都是本地的
• 无遥测 --未收集或传输使用数据
• 仅限本地主机 --默认情况下，管理器UI绑定到localhost
• 路径验证 --验证文件路径以防止目录遍历
• 输入验证 --所有MCP工具输入均已AJV模式验证

建议：

1. 不要将Manager UI暴露给公共网络
2. 保持软件包更新： npm update -g @teknologika/mcp-codebase-search
3. 运行安全审核： npm audit

许可证

MIT许可证——见 许可证 了解详情。

作者

技术

致谢

• 模型上下文协议 --MCP规范
• LanceDB --矢量数据库
• 树保姆 --代码解析
• 拥抱脸 --嵌入模型
• 禁食 --Web框架

______________________________________________________________________

问题或议题？ 打开一个问题