MCP CodeHub Server

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 서버 추가:

• Command: pnpm dev (또는 node dist/server.js)
• Working Directory: 프로젝트 경로
• Transport: 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 하위에 있는지 확인