MCP Codehub Server

MCP CodeHub服务器

用TypeScript实现的便携式MCP服务器 -与Cursor/Claude配合使用，可以安全地浏览和搜索代码库的工具。

主要功能

• 🌳 安全的目录树扫描 -通过深度限制和文件数量限制进行保护
• 🔍 快速代码搜索 -优先使用ripgrep，支持JavaScript回退
• 📄 读取片断 -安全地读取文件的特定行范围
• ✏️ 写入文件 -文件创建和内容修改功能
• 🛡️ 安全优先 -自动排除secrets、node_modules等敏感文件
• 🪟 Windows兼容 -路径规范化和Windows环境优化

🚀 快速入门

1.安装

# 프로젝트 디렉토리로 이동
cd mcp-codehub-server

# 의존성 설치
pnpm install
# 또는
npm install

2.首选参数

创建首选参数文件并设置代码根路径：

# .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=true

3.运行服务器

开发模式（建议）

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环境中，路径自动规范为斜杠（/）。
• 权限：只能扫描服务器可以访问的目录。

📖 故障排除

如果服务器无法启动

1. 验证Node.js版本是否为18.18或更高版本
2. 验证是否正确安装了依赖性（pnpm install)
3. .env 文件的 CODE_ROOTS 验证路径是否正确

如果搜索速度较慢

1. USE_RIPGREP=true设置为并安装ripgrep
2. MAX_ENTRIES_PER_DIR 降低价格
3. DENY_GLOBS将不需要的目录添加到

如果找不到文件

1. ALLOW_GLOBS 确保模式中包含相应的文件扩展名
2. DENY_GLOBS 确保未被模式排除在外
3. 文件实际设置为 CODE_ROOTS 检查是否在子项中