MCP Codebase Search

MCP开发工具

提供方 teknologika · 包名 mcp-codebase-ingest

开发工具 stdio · 本地进程 Token 社区 / 第三方 Claude
查看接入方式

一个本地优先的代码库语义搜索系统,使用模型上下文协议(MCP)进行集成,帮助AI助手发现现有代码实现,避免重复代码和错误文件编辑。

一句话选型结论

按资料字段整理

MCP Codebase Search 属于开发工具类 MCP 服务器,stdio · 本地进程,Token,可直接接入 Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类开发工具 传输方式stdio · 本地进程 鉴权Token 部署方式本地部署
GitHub 星标 2 仓库热度,无公开仓库时显示未标注
工具数 9 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

开发工具
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量9暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

代码搜索TypeScript本地部署语义分析本地处理多语言支持AI集成

安装与配置

stdio · 本地进程 Token
客户端在本机拉起子进程,数据不出本机
npx mcp-codebase-ingest --path ./my-project --name my-project

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 9 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
代码与仓库操作

在对话里直接查代码、提 issue、走 PR,省掉来回切工具。

本地命令与脚本

把构建、测试、格式化这类重复命令交给模型执行。

接口联调与测试

让模型调你的接口、跑一遍用例,快速定位问题。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 9 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在开发工具场景里让模型直接调用外部能力的人。
  • 已经在用 Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
MCP Codebase Search当前 9 stdio · 本地进程 本地部署 有 2026-05-17
Git 838e2ec1 12 stdio · 本地进程 本地部署 有 2026-05-17
Markitdown MCP 2c653a5f 1 stdio · 本地进程 本地部署 有 2026-05-17
JavaGuide 未标注 stdio · 本地进程 本地部署 有 2026-04-11
awesome-claude-skills 未标注 stdio · 本地进程 本地部署 有 2026-04-26
Context7 831acf40 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

开发工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方teknologika上游标注的维护方 teknologika
分类开发工具本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时mcp-codebase-ingest · Node.js本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

26.1 KB
来自项目仓库与上游目录的原文,未做删改

@技术/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.

为什么使用这个?

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

特性

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

安装

全局安装(推荐)```bash

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


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

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

### 本地安装```bash
npm install @teknologika/mcp-codebase-search

然后与一起使用 npx:```bash
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.为你的第一个代码库建立索引```bash
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):```json
{
"mcpServers": {
"codebase-search": {
"command": "mcp-codebase-search",
"args": []
}
}
}

3.设置您的代理.md

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

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: `<2–4 searches you will run>` - 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```bash
mcp-codebase-manager

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

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

用法

摄入CLI

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

基本用法```bash

mcp-codebase-ingest --path --name


#### 选项

|选项|说明|必填|示例|
|--------|-------------|----------|---------|
| `-p, --path` |代码库目录的路径|是| `--path ./my-project` |
| `-n, --name` |代码库的唯一名称|是| `--name my-project` |
| `-c, --config` |配置文件路径|否| `--config ./config.json` |
| `--no-gitignore` |禁用.gitignore过滤|否| `--no-gitignore` |

#### 示例```bash
# 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助手提供了搜索和探索代码库的工具。

启动服务器```bash

mcp-codebase-search


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

#### 可用工具

##### `list_codebases`

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

**输入:** 无

**输出:**```json
{
"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

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

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


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

**输出:**```json
{
"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

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

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


**输出:**```json
{
"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

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

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


**输出:**```json
{
"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 您需要周围的上下文,而无需获取整个文件。

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


**输出:**```json
{
"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

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

输入:```json
{
"codebaseName": "my-project"
}


**输出:**```json
{
"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

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

输入:```json
{
"name": "my-project"
}


**输出:**```json
{
"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

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

输入:```json
{
"name": "my-project",
"verbose": false
}


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

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

**输出:**```json
{
"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。如果管理器服务器尚未运行,则自动启动它。

输入: 无

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


### 管理器UI

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

#### 启动管理器```bash
mcp-codebase-manager

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

特性

搜索选项卡:

  • 跨所有索引代码库的语义搜索
  • 按代码库和最大结果筛选
  • 排除测试文件和库文件
  • 带有颜色编码置信度评分的可折叠结果:
  • 🟢 绿色(0.80–1.00):非常匹配
  • 🟡 黄色(0.60–0.79):匹配良好
  • 🔵 蓝色(0.00–0.59):较低匹配

管理选项卡:

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

经理控制:

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

配置

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

配置文件示例```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"
}


### 配置选项

|章节|选项|描述|默认|
|---------|--------|-------------|---------|
| `lancedb` | `persistPath` |LanceDB存储目录| `~/.codebase-memory/lancedb` |
| `embedding` | `modelName` |拥抱脸部模型| `Xenova/all-MiniLM-L6-v2` |
| `embedding` | `cachePath` |模型缓存目录| `~/.codebase-memory/models` |
| `server` | `port` |管理器UI端口| `8008` |
| `server` | `host` |管理器UI主机| `localhost` |
| `server` | `sessionSecret` |会话cookie机密|自动生成|
| `ingestion` | `batchSize` |每个嵌入批次的块数| `100` |
| `ingestion` | `maxFileSize` |最大文件大小(字节)| `1048576` |
| `ingestion` | `maxChunkTokens` |每个区块的最大令牌数| `512` |
| `ingestion` | `chunkOverlapTokens` |块之间的令牌重叠| `50` |
| `ingestion` | `storeFullFiles` |存储完整文件内容 `get_file_content` | `true` |
| `search` | `defaultMaxResults` |默认结果限制| `50` |
| `search` | `cacheTimeoutSeconds` |搜索缓存TTL(重新扫描时自动清除)| `60` |
| `logging` | `level` |日志冗长| `info` |

## MCP客户端配置

### 克劳德桌面版

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

**窗户:** `%APPDATA%\Claude\claude_desktop_config.json````json
{
"mcpServers": {
"codebase-search": {
"command": "mcp-codebase-search",
"args": []
}
}
}

其他MCP客户端```json

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


### 验证配置

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

## 支持的语言

|语言|扩展|块类型|
|----------|-----------|-------------|
| **TypeScript** | `.ts`, `.tsx` |函数、类、方法、接口|
| **JavaScript** | `.js`, `.jsx` |函数、类、方法|
| **python** | `.py` |函数、类、方法|
| **Java** | `.java` |类、方法、字段、接口|
| **C** | `.cs` |类、方法、属性、接口|
| **斯维尔特** | `.svelte` |组件|
| **超文本标记语言** | `.html` |文件|
| **CSS/scs** | `.css`, `.scss` |文件|
| **JSON** | `.json` |文件|
| **YAML** | `.yaml`, `.yml` |文件|
| **标记语言** | `.md` |章节|

不产生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)

行结构:```json
{
"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代码库搜索”```bash
npm install -g @teknologika/mcp-codebase-search
# or use npx
npx mcp-codebase-search

“初始化LanceDB失败”```bash

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


#### “嵌入模型下载失败”```bash
# 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无法打开/端口正在使用中”```bash
# 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):```json
    { "ingestion": { "batchSize": 200 } }
- **使用SSD存储** 对于LanceDB持久性目录
- **排除不必要的文件** 通过 `.gitignore`
- **定期重新扫描** --呼叫 `update_codebase_scan` 发生重大变化后

## 发展

### 设置```bash
git clone https://github.com/teknologika/mcp-codebase-search.git
cd mcp-codebase-search
npm install
npm run build

脚本```bash

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框架

问题或议题? 打开一个问题 GitHub

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
MCP Codebase Search 怎么安装?

在客户端按下面的安装命令接入:npx mcp-codebase-ingest --path ./my-project --name my-project。对应的包名是 mcp-codebase-ingest。装完在客户端配置里引用同一个包或端点。

MCP Codebase Search 怎么在 Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

MCP Codebase Search 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

MCP Codebase Search 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

MCP Codebase Search 支持哪些客户端?

资料标注支持 Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

MCP Codebase Search 能提供哪些能力?

资料显示约 9 个工具;能力标签包括 代码搜索、本地处理、TypeScript、Claude。具体工具清单以官方文档为准。

MCP Codebase Search 需要什么运行环境?

运行时为 Node.js;属于本地进程,需要在本机装好运行环境。

MCP Codebase Search 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。