🚀 Revolutionary MCP Server

완전히 새로운 차원의 모듈형 MCP 서버

하나의 MCP 서버를 통해 여러 MCP 클라이언트에서 비슷한 결과를 만들어내기 위한 목적의 모듈형 MCP 서버입니다. 이 프로젝트에 구성된 도구들은 프로그래밍 프로젝트를 만들거나 자료를 리서치를 하는데 있어서 기존 단순 도구보다 훨씬 진보된 동작을 만들도록 목표하고 있습니다.

⚡ 혁신적 특징

🎯 100% MCP SDK 표준 준수

• McpServer 고수준 API: 저수준 Server 클래스 대신 권장되는 McpServer 사용
• registerTool() 메서드: setRequestHandler() 대신 표준 도구 등록 방식
• StdioServerTransport: 표준 STDIO 전송 계층 사용
• 완전한 프로토콜 준수: 2024-11-05 프로토콜 버전 완벽 지원

⚡ 현대적 기술 스택

• Hono Framework: Express를 완전히 대체한 고성능 웹 프레임워크
• Bun Runtime: Node.js보다 빠른 차세대 JavaScript 런타임
• TypeScript: 완전한 타입 안전성
• Zero Express: 무거운 Express 종속성 완전 제거

🔧 진보된 아키텍처

• 완전 분리된 Transport: STDIO와 HTTP가 독립적으로 구현
• 동적 플러그인 시스템: 런타임 플러그인 로드/리로드
• 통합 도구 관리: 플러그인별 도구 자동 등록
• 실시간 상태 모니터링: 서버 상태 및 통계 실시간 조회

프로젝트 목표 vs MCPO 비교

현재 프로젝트의 목표

• 직접적인 MCP 서버: 순수 MCP 프로토콜 구현
• VS Code 1차 지원: VS Code MCP 클라이언트와의 완벽한 호환성
• 모듈형 플러그인 시스템: 개인 스크립트를 쉽게 MCP 도구로 변환
• 다중 클라이언트 호환: 향후 다양한 MCP 클라이언트 지원 확장

MCPO (MCP-to-OpenAPI Proxy)의 목표

• 프록시 계층: 기존 MCP 서버를 OpenAPI로 변환
• 웹 도구 호환성: OpenAPI 기반 도구들과의 연동
• 변환 특화: MCP → OpenAPI 변환에 집중

결론: 두 프로젝트는 상호 보완적이며 목적이 다릅니다. MCPO를 사용하려면 현재 프로젝트를 MCPO의 백엔드 MCP 서버로 활용할 수 있습니다.

통신 방식

현재 프로젝트는 표준 MCP 프로토콜을 따릅니다:

• STDIO: VS Code와의 직접 연결 (권장)
• HTTP JSON-RPC: 웹 기반 클라이언트 지원
• 요청-응답 방식: 단순하고 안정적인 통신
• 스트리밍 미지원: 복잡성을 피하고 신뢰성에 집중

특징

• MCP SDK 표준 준수: @modelcontextprotocol/sdk 표준 구현
• 모듈형 플러그인 시스템: 다양한 유형의 플러그인을 지원
• 개인 스크립트 통합: JavaScript/TypeScript 스크립트를 쉽게 MCP 도구로 변환
• 기존 MCP 서버 통합: 외부 MCP 서버를 플러그인으로 추가
• 설정 기반 관리: JSON 설정 파일로 모든 플러그인 관리
• 동적 로딩: 런타임에 플러그인 로드/언로드 지원

설치 및 실행

# 종속성 설치
bun install

# 개발 모드 (HTTP)
bun run dev

# 개발 모드 (STDIO)
bun run dev:stdio

# 빌드
bun run build

# 프로덕션 실행
bun run start

플러그인 사용 방법

VSCode 설정

VSCode에서 이 MCP 서버를 사용하는 방법을 설명합니다. 웹 기반 접속이 권장되며, STDIO는 특별한 경우나 대체 방법으로 사용됩니다.

방법 1: HTTP/웹 기반 연결 (권장)

1. MCP 서버를 HTTP 모드로 시작:

# 개발 중일 때
bun run dev

# 또는 프로덕션 빌드 후
bun run build
bun run start

2. VSCode MCP 설정 파일 (.vscode/mcp.json) 생성:

HTTP 연결 (로컬 개발):

{
  "servers": {
    "personal-mcp-server": {
      "transport": {
        "type": "http",
        "url": "https://your-domain.com:3000"
      }
    }
  },
  "inputs": []
}

3. 서버 상태 확인:

# 도구 목록 확인
curl -X POST https://your-domain.com:3000 
  -H "Content-Type: application/json" 
  -d '{"method": "tools/list", "params": {}}'

# 플러그인 상태 확인  
curl -X POST https://your-domain.com:3000 
  -H "Content-Type: application/json" 
  -d '{"method": "plugins/list", "params": {}}'

방법 2: STDIO 연결 (대체 방법)

STDIO 방식은 다음과 같은 특별한 경우에만 사용하는 것을 권장합니다:

• 네트워크 연결이 제한된 환경
• 보안상 HTTP 포트를 열 수 없는 경우
• 디버깅이나 개발 목적

1. 프로젝트 빌드:

bun run build

2. VSCode MCP 설정 파일 (.vscode/mcp.json) 생성:

{
  "servers": {
    "personal-mcp-server": {
      "command": "bun",
      "args": ["run", "dist/index.js", "--mode=stdio"],
      "cwd": "/home/labeldock/bun-mcp-server"
    }
  },
  "inputs": []
}

설정 확인 및 문제 해결

1. 플러그인 로드 상태 확인:

   • HTTP 모드에서는 브라우저로 http://localhost:3000/health 접속
   • 로그에서 플러그인 초기화 메시지 확인

2. 일반적인 문제:

   • 포트 충돌: 기본 포트 3000이 사용 중인 경우 다른 포트 사용
   • 플러그인 로드 실패: mcp-config.json 설정과 플러그인 파일 경로 확인
   • 권한 문제: 스크립트 파일의 실행 권한 확인

플러그인 유형

1. Local Script Plugin

개인 JavaScript/TypeScript 스크립트를 MCP 도구로 변환

// plugins/my-script.js
export const tools = [
  {
    name: 'my_tool',
    description: 'My custom tool',
    inputSchema: {
      type: 'object',
      properties: {
        input: { type: 'string' }
      }
    }
  }
];

export async function execute(toolName, args) {
  // 도구 실행 로직
  return { content: [{ type: 'text', text: 'Hello from my tool!' }] };
}

2. External Server Plugin

외부 MCP 서버를 서브프로세스로 실행

{
  "name": "my-external-server",
  "type": "external-server", 
  "command": "node ./path/to/external-server.js",
  "enabled": true
}

3. NPM Package Plugin

NPM 패키지로 설치된 MCP 서버

{
  "name": "my-npm-mcp",
  "type": "npm-package",
  "path": "my-mcp-package",
  "enabled": true
}

설정 파일 (mcp-config.json)

{
  "server": {
    "name": "Personal MCP Server",
    "version": "1.0.0",
    "description": "A modular MCP server"
  },
  "plugins": [
    {
      "name": "system-tools",
      "type": "local-script",
      "path": "./plugins/example-script.js",
      "enabled": true
    }
  ],
  "settings": {
    "logLevel": "info",
    "timeout": 30000,
    "maxConcurrent": 10
  }
}

예제 플러그인

시스템 도구 (system-tools)

• get_mcp_system_info: 시스템 정보 조회
• run_command: 안전한 셸 명령 실행

파일 관리자 (file-manager)

• list_directory_tree: 디렉토리 트리 구조 표시 (보안상 tmp 외 파일 접근 제한)
• write_file: 파일 쓰기 (주석 처리됨)

API

도구 목록 조회

curl -X POST http://localhost:3000 \\
  -H "Content-Type: application/json" \\
  -d '{"method": "tools/list", "params": {}}'

도구 실행

curl -X POST http://localhost:3000 \\
  -H "Content-Type: application/json" \\
  -d '{
    "method": "tools/call",
    "params": {
      "name": "get_mcp_system_info",
      "arguments": {"type": "basic"}
    }
  }'

플러그인 목록 조회

curl -X POST http://localhost:3000 \\
  -H "Content-Type: application/json" \\
  -d '{"method": "plugins/list", "params": {}}'

개발 가이드

새로운 스크립트 플러그인을 추가하려면:

1. plugins/ 디렉토리에 스크립트 파일 생성
2. tools 배열과 execute 함수 정의
3. mcp-config.json에 플러그인 설정 추가
4. 서버 재시작 또는 플러그인 리로드

라이선스

MIT License