使用说明

代码库MCP服务器

一种模型上下文协议（MCP）服务器，可以智能地加载和上下文化来自任何应用程序项目的代码库，而不管技术栈如何。

🚀 特性

语言无关：支持任何编程语言（TypeScript、Java、Rust、Go、Python、C++等）
多模块支持：处理monorepos和复杂的项目结构
智能穿越：尊重 .gitignore 和自定义忽略模式
相关性分析：自动检测和解析package.json、pom.xml、Cargo.toml、go.mod中的依赖关系
Neo4j图形数据库 （可选）：用于高级代码库分析的持久性基于图的索引
- 代码库加载时的自动索引
- 基于图形的关系和依赖关系查询
- 优雅地回退到仅文件系统模式
IDE集成：与VS Code和IntelliJ IDEA无缝协作
有效搜索：快速的文件和内容搜索功能
上下文感知：向AI助手提供有关代码库的结构化信息

💾 安装

全球安装

npm install -g codebase-mcp-server

本地安装

npm install codebase-mcp-server

来源

git clone https://github.com/Borelli-7/codebase-mcp-server.git
cd codebase-mcp-server
npm install
npm run build

🏃 快速开始

1.构建服务器

npm install
npm run build

2.运行服务器

npm start

或者在开发模式下：

npm run dev

3.配置编辑器

按照您首选编辑器的设置指南进行操作：

⚙️ 配置

服务器可以通过MCP工具调用或环境变量进行配置。

Neo4j集成（可选）

通过环境变量配置Neo4j，启用基于持久图的索引：

# Quick setup with Docker
docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/your-password \
  neo4j:5

# Set environment variables
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=your-password
export NEO4J_DATABASE=neo4j  # Optional, default: neo4j

或者创建一个 .env 项目根目录中的文件：

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your-password
NEO4J_DATABASE=neo4j

看 .env.示例用于配置模板。

启用Neo4j时：

代码库会自动编入索引 set-codebase-path
图形查询为结构和搜索操作提供了增强的性能
新的图形驱动工具可用

未配置Neo4j时：

服务器仅在文件系统模式下运行
所有原始工具工作不变
无性能影响

默认忽略模式

服务器会自动忽略常用目录：

node_modules
.git
dist, build, out, target
.next, .nuxt
coverage, .nyc_output
日志文件和特定于操作系统的文件

自定义忽略模式

使用添加自定义图案 configure-ignore-patterns 工具：

{
  "action": "add",
  "patterns": ["*.test.ts", "__mocks__", "temp"]
}

🛠️ 工具参考

服务器公开了以下MCP工具：

1.设置代码库路径

设置要分析的代码库的路径。

输入架构：

{
  path: string  // Absolute path to the codebase directory
}

输出架构：

{
  success: boolean
  message: string
  path: string
}

例子：

{
  "path": "/home/user/projects/my-app"
}

2.列出代码库结构

获取代码库目录结构的概述。

输入架构：

{
  maxDepth?: number        // Maximum depth to traverse (default: 3)
  includeHidden?: boolean  // Include hidden files/folders (default: false)
}

输出架构：

{
  success: boolean
  structure: Array<{
    path: string
    type: 'file' | 'directory'
    size?: number
    language?: string
  }>
  totalFiles: number
  totalDirectories: number
}

3.加载文件内容

从代码库加载特定文件的内容。

输入架构：

{
  relativePath: string  // Relative path from codebase root
}

输出架构：

{
  success: boolean
  path: string
  content?: string
  language?: string
  lines?: number
  size?: number
}

4.搜索代码库

搜索与模式匹配或包含特定内容的文件。

输入架构：

{
  query: string                    // Search query
  searchType: 'filename' | 'content'  // Type of search
  filePattern?: string             // File pattern filter (e.g., "*.ts")
  maxResults?: number              // Maximum results (default: 50)
}

输出架构：

{
  success: boolean
  results: Array<{
    path: string
    matches?: number
    preview?: string
  }>
  totalResults: number
}

5.获取模块依赖关系

分析和检索模块或项目的依赖关系。

输入架构：

{
  modulePath?: string  // Relative path to module (default: root)
}

输出架构：

{
  success: boolean
  dependencies: Array<{
    name: string
    version?: string
    type: 'runtime' | 'dev' | 'peer' | 'optional'
  }>
  devDependencies?: string[]
}

支持的格式：

Node.js/TypeScript： package.json
Java pom.xml
锈蚀： Cargo.toml
去： go.mod

6.配置忽略模式

添加、删除或列出文件遍历的忽略模式。

输入架构：

{
  action: 'add' | 'remove' | 'list'
  patterns?: string[]  // Patterns to add or remove
}

输出架构：

{
  success: boolean
  currentPatterns: string[]
  message: string
}

🔷 Neo4j驱动工具

配置Neo4j时，可以使用以下工具：

7.索引代码库

手动触发将当前代码库重新索引到Neo4j中。

输入架构：

{
  force?: boolean  // Force re-index even if already indexed
}

输出架构：

{
  success: boolean
  totalFiles: number
  totalDirectories: number
  totalDependencies: number
  duration: number  // milliseconds
}

8.获取代码库统计信息

从索引代码库图中获取聚合统计信息。

输入架构：

{}

输出架构：

{
  success: boolean
  indexedAt: string
  totalFiles: number
  totalDirectories: number
  totalDependencies: number
  topLanguages: Array<{
    language: string
    count: number
  }>
  totalSize: number
}

9.获取依赖关系图

从Neo4j中检索完整的依赖关系图。

输入架构：

{
  depth?: number  // Maximum depth for dependency tree (default: all)
}

输出架构：

{
  success: boolean
  dependencies: Array<{
    name: string
    version: string
    type: 'runtime' | 'dev' | 'peer' | 'optional'
  }>
  totalCount: number
}

10.获取目录摘要

从图中获取特定目录的聚合统计信息。

输入架构：

{
  dirPath: string  // Relative path to directory
}

输出架构：

{
  success: boolean
  path: string
  totalFiles: number
  languages: Record<string, number>  // language -> file count
  totalSize: number
  totalLines: number
}

🖥️ 编辑器集成

VS Code

看 VS代码设置指南详细说明。

快速配置：

{
  "github.copilot.advanced": {
    "mcp": {
      "servers": {
        "codebase": {
          "command": "node",
          "args": ["/absolute/path/to/codebase-mcp-server/dist/index.js"]
        }
      }
    }
  }
}

智能J IDEA

看 IntelliJ IDEA设置指南详细说明。

快速配置：

{
  "mcpServers": {
    "codebase": {
      "command": "node",
      "args": ["/absolute/path/to/codebase-mcp-server/dist/index.js"]
    }
  }
}

📚 例子

示例1：探索一个TypeScript项目

1. Set codebase path: /home/user/projects/my-ts-app
2. List structure with max depth 2
3. Search for TypeScript files containing "interface"
4. Load src/types/User.ts
5. Get module dependencies

示例2：分析Java应用程序

1. Set codebase path: /home/user/projects/my-java-app
2. List structure
3. Search for Java files with "Controller"
4. Load src/main/java/com/example/UserController.java
5. Get Maven dependencies

示例3：使用Rust

1. Set codebase path: /home/user/projects/my-rust-project
2. Search for Rust files containing "async"
3. Load src/main.rs
4. Get Cargo dependencies

示例4：多模块项目

1. Set codebase path: /home/user/projects/monorepo
2. List structure with max depth 4
3. Get dependencies for module ./packages/frontend
4. Get dependencies for module ./packages/backend

🏗️ 建筑

组件

MCP服务器 (src/index.ts)
- 处理MCP协议通信
- 注册并公开工具
- 使用stdio传输
- 线Neo4j集成（可选）
代码库加载器 (src/codebaseLoader.ts)
- 采用双源策略的文件系统遍历
- Neo4j图形查询（如果可用）
- 自动回退到文件系统
- 语言检测
- 内容解析
- 依赖性分析
配置项管理 (src/config.ts)
- 配置状态管理
- 忽略模式管理
- 从环境配置Neo4j
Neo4j服务 (src/neo4jService.ts) [可选]
- 数据库连接管理
- Cypher查询执行助手
- 架构初始化（约束和索引）
- 优雅的错误处理
Neo4j索引器 (src/neo4jIndexer.ts) [可选]
- 批量索引管道（500件/批）
- 图形节点/关系创建
- 依赖解析集成
- 针对大型代码库进行了性能优化
公用事业 (src/utils.ts)
- 忽略过滤器初始化
- 语言检测（37+扩展）
- 模式匹配

支持的语言

服务器检测30多种编程语言：

网络：TypeScript、JavaScript、HTML、CSS、SCSS
后端：Java、Python、Go、Rust、C++、C#、Ruby、PHP
移动：斯威夫特、科特林、达特
其他：Shell、SQL、R、MATLAB、Scala等

依赖性检测

自动解析依赖关系文件：

语言/框架	文件	检测到的信息
Node.js/TypeScript	package.json	依赖关系、devDependencies、对等依赖关系
Java（Maven）	pom.xml	artifactId，groupId
Rust	Cargo.toml	依赖关系，开发依赖关系
Go	Go.mod	require语句

🔧 发展

先决条件

Node.js 18.0.0或更高版本
npm或纱线
Neo4j 5.x（可选，用于基于图形的功能）
- Docker： docker run -d --name neo4j -p 7474:7474 -p 7687:7687 -e NEO4J_AUTH=neo4j/password neo4j:5
- 或从本地安装 neo4j.com/下载

设置

# Clone the repository
git clone https://github.com/Borelli-7/codebase-mcp-server.git
cd codebase-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Watch mode (auto-rebuild)
npm run watch

项目结构

codebase-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── codebaseLoader.ts     # Codebase loading logic (dual-source)
│   ├── config.ts             # Configuration management
│   ├── neo4jService.ts       # Neo4j connection & queries
│   ├── neo4jIndexer.ts       # Graph indexing pipeline
│   └── utils.ts              # Shared utilities
├── tests/
│   └── utils.test.ts         # Unit tests
├── dist/                     # Compiled output
├── .env.example              # Environment variable template
├── VSCODE_SETUP.md          # VS Code integration guide
├── INTELLIJ_SETUP.md        # IntelliJ IDEA integration guide
├── vitest.config.ts         # Test configuration
├── package.json
├── tsconfig.json
└── README.md

脚本

npm run build -将TypeScript编译为JavaScript
npm run dev -使用tsx在开发模式下运行
npm run watch -开发观看模式
npm start -运行已编译的服务器
npm test -使用vitest运行测试
npm run test:watch -在监视模式下运行测试

🐛 故障排除

服务器未启动

验证Node.js版本：

node --version  # Should be 18.0.0 or higher

重建项目：
```
npm install
npm run build
```
检查错误：
```
node dist/index.js
```

路径问题

在配置中始终使用绝对路径。获取绝对路径：

macOS/Linux：

cd /path/to/codebase-mcp-server
pwd

窗户：

cd C:\path\to\codebase-mcp-server
cd

权限错误

在macOS/Linux上，确保执行权限：

chmod +x dist/index.js

大型代码库性能

对于大型代码库：

启用Neo4j 用于持久索引和更快的查询
添加更多忽略模式
限制 maxDepth 上市结构时
在搜索中使用特定的文件模式
设置特定模块的代码库路径

Neo4j连接问题

服务器未连接到Neo4j：

验证Neo4j是否正在运行：

docker ps | grep neo4j
# or
neo4j status

测试连接：

# Check Neo4j browser at http://localhost:7474

验证环境变量：

echo $NEO4J_URI
echo $NEO4J_USER
echo $NEO4J_PASSWORD

检查服务器日志（stderr）：
- 寻找 [Neo4j] Connected successfully 或连接错误
- 连接失败时，服务器将回退到仅文件系统模式

索引性能：

对于大型代码库（10k+文件：~20-30s），首次索引可能需要时间
后续查询使用该图，速度要快得多
使用 index-codebase 在重大更改后手动重新索引的工具

调试日志

服务器记录到stderr（而不是stdout）。检查编辑器的MCP日志：

VS Code：输出面板>GitHub Copilot
智能J：帮助>显示登录Finder/Explorer

🤝 贡献

欢迎投稿！请按照以下步骤操作：

克隆该仓库
创建要素分支： git checkout -b feature/my-feature
提交您的更改： git commit -am 'Add new feature'
推到分支： git push origin feature/my-feature
提交拉取请求

开发指南

遵循TypeScript的最佳实践
为新功能添加测试
更新文档
使用有意义的提交消息

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

使用说明

代码库MCP服务器

🚀 特性

📋 目录

💾 安装

全球安装

本地安装

来源

🏃 快速开始

1.构建服务器

2.运行服务器

3.配置编辑器

⚙️ 配置

Neo4j集成（可选）

默认忽略模式

自定义忽略模式

🛠️ 工具参考

1.设置代码库路径

2.列出代码库结构

3.加载文件内容

4.搜索代码库

5.获取模块依赖关系

6.配置忽略模式

🔷 Neo4j驱动工具

7.索引代码库

8.获取代码库统计信息

9.获取依赖关系图

10.获取目录摘要

🖥️ 编辑器集成

VS Code

智能J IDEA

📚 例子

示例1：探索一个TypeScript项目

示例2：分析Java应用程序

示例3：使用Rust

示例4：多模块项目

🏗️ 建筑

组件

支持的语言

依赖性检测

🔧 发展

先决条件

设置

项目结构

脚本

🐛 故障排除

服务器未启动

路径问题

权限错误

大型代码库性能

Neo4j连接问题

调试日志

🤝 贡献

开发指南

📄 许可证

🙏 致谢

📞 支持

🔗 链接

相关 MCP

代码索引分析工具

YouTube字幕提取服务

代码运行服务

代码分析服务器

GitHub仓库解析工具

VSCode MCP桥接工具