MCP CodeHub服务器
用TypeScript实现的便携式MCP服务器 -与Cursor/Claude配合使用，可以安全地浏览和搜索代码库的工具。
主要功能
- 🌳 安全的目录树扫描 -通过深度限制和文件数量限制进行保护
- 🔍 快速代码搜索 -优先使用ripgrep，支持JavaScript回退
- 📄 读取片断 -安全地读取文件的特定行范围
- ✏️ 写入文件 -文件创建和内容修改功能
- 🛡️ 安全优先 -自动排除secrets、node_modules等敏感文件
- 🪟 Windows兼容 -路径规范化和Windows环境优化
🚀 快速入门
1.安装
# 프로젝트 디렉토리로 이동
cd mcp-codehub-server
# 의존성 설치
pnpm install
# 또는
npm install2.首选参数
创建首选参数文件并设置代码根路径：
# .env 파일 생성
cp .env.example .env.env 编辑文件以设置代码根路径：
# 하나 이상의 코드 루트 (세미콜론으로 구분)
CODE_ROOTS=C:/Users/YourName/Projects;D:/workspace
# 허용할 파일 패턴 (쉼표로 구분)
ALLOW_GLOBS=**/*.{ts,tsx,js,jsx,py,java,kt,go,rb,rs,cpp,c,h,md,json,yml,yaml}
# 제외할 파일/디렉토리 패턴 (쉼표로 구분)
DENY_GLOBS=**/node_modules/**,**/.git/**,**/dist/**,**/build/**,**/.next/**
# 보안 및 성능 제한
MAX_DEPTH=6
MAX_ENTRIES_PER_DIR=500
MAX_SNIPPET_BYTES=20000
# ripgrep 사용 (빠른 검색을 위해 권장)
USE_RIPGREP=true3.运行服务器
开发模式（建议）
pnpm dev生产构建
pnpm build
pnpm start连接客户端
在Cursor中使用
在项目根目录或全局设置中 mcp.json 创建文件：
{
"mcpServers": {
"codehub": {
"command": "pnpm",
"args": ["--prefix", "path/to/mcp-codehub-server", "dev"],
"cwd": "path/to/mcp-codehub-server",
"transport": "stdio"
}
}
}在Claude Desktop中使用
在Claude Desktop设置中添加本地MCP服务器：
- 命令:
pnpm dev（或node dist/server.js) - 工作目录：项目路径
- 运输：stdio
🛠️ 可用工具
scan_tree
以JSON格式返回目录结构。
scan_tree({
roots?: string[], // 스캔할 루트 디렉토리 (기본값: 환경변수)
maxDepth?: number, // 최대 깊이 (기본값: 6)
includeHidden?: boolean // 숨김 파일 포함 여부 (기본값: false)
})search_code
在代码中搜索关键字或正则表达式。
search_code({
query: string, // 검색할 텍스트/정규식 (필수)
globs?: string[], // 파일 패턴 (기본값: ["**/*"])
maxResults?: number // 최대 결과 수 (기본값: 200)
})read_snippet
读取文件的特定行范围。
read_snippet({
path: string, // 파일 경로 (필수)
start: number, // 시작 라인 (필수)
end: number, // 끝 라인 (필수)
root: string, // 루트 디렉토리 (선택)
});write_file
在文件中创建内容。
write_file({
path: string, // 파일 경로 (필수)
content: string, // 파일 내용 (필수)
root: string, // 루트 디렉토리 (선택)
});📋 使用示例
1.确认项目结构
// 현재 설정된 모든 루트의 디렉토리 구조 확인
scan_tree({ maxDepth: 3 });2.搜索函数
// React 컴포넌트에서 useState 사용 찾기
search_code({
query: "useState",
globs: ["**/*.tsx", "**/*.jsx"],
});3.确认特定文件内容
// package.json의 scripts 섹션 확인
read_snippet({
path: "package.json",
start: 5,
end: 15,
});4.创建/修改文件
// 새로운 설정 파일 생성
write_file({
path: "config/database.js",
content: `module.exports = {
host: 'localhost',
port: 3306,
database: 'myapp'
};`,
});
// 기존 파일 수정
write_file({
path: "src/constants.ts",
content: "export const API_URL = 'https://api.example.com';",
});🔧 高级设置
安装Ripgrep（提高性能）
建议安装ripgrep以更快地进行搜索：
# Windows (Chocolatey)
choco install ripgrep
# Windows (Scoop)
scoop install ripgrep
# macOS (Homebrew)
brew install ripgrep
# Ubuntu/Debian
sudo apt install ripgrep自定义安全设置
排除其他敏感文件或目录的步骤 DENY_GLOBS请修改：
DENY_GLOBS=**/node_modules/**,**/.git/**,**/dist/**,**/.env,**/*.key,**/secrets/**🚨 注意事项
- 保安:
DENY_GLOBS设置会自动排除敏感文件，但如果需要额外的安全性，请扩展模式。 - 性能:
MAX_DEPTH哇MAX_ENTRIES_PER_DIR您可以通过设置来调整性能。 - 路径：在Windows环境中，路径自动规范为斜杠（/）。
- 权限：只能扫描服务器可以访问的目录。
📖 故障排除
如果服务器无法启动
- 验证Node.js版本是否为18.18或更高版本
- 验证是否正确安装了依赖性（
pnpm install) .env文件的CODE_ROOTS验证路径是否正确
如果搜索速度较慢
USE_RIPGREP=true设置为并安装ripgrepMAX_ENTRIES_PER_DIR降低价格DENY_GLOBS将不需要的目录添加到
如果找不到文件
ALLOW_GLOBS确保模式中包含相应的文件扩展名DENY_GLOBS确保未被模式排除在外- 文件实际设置为
CODE_ROOTS检查是否在子项中