MCP Tool Hub

IT 자동화 팀을 위해 TypeScript로 구축된 모듈식 확장형 Model Context Protocol 멀티 서버 허브입니다.

LLM이 파일, Git, 웹 콘텐츠, 영구 메모리와 같은 실제 도구에 액세스할 수 있도록 합니다. Ansible을 통해 여러 클라이언트 머신에 동시에 배포하세요.

아키텍처

mcp-tool-hub/
├── packages/
│   ├── core/              ← Shared types + BaseMCPServer abstract class
│   ├── server-filesystem/ ← Sandboxed local file access (read/write/list/delete)
│   ├── server-git/        ← Git log, diff, file contents, branches, status
│   ├── server-fetch/      ← Web fetching: HTML, JSON APIs, URL health checks
│   └── server-memory/     ← Persistent JSON knowledge base (survives restarts)
├── host/                  ← Orchestrator: registry + CLI + stdio JSON interface
├── ansible/               ← Playbook, inventory, systemd service templates
└── docs/                  ← How to add new servers (with template)

이 아키텍처는 Model Context Protocol 패턴을 따릅니다:

각 서버는 완전히 독립적입니다(자체 패키지, 자체 빌드).
호스트의 레지스트리는 런타임에 toolName → server를 매핑합니다.
CLI는 stdio JSON 인터페이스를 노출합니다. 모든 LLM 통합은 stdin으로 {"toolName":"...", "arguments":{...}}를 보내고 stdout에서 결과를 읽습니다.
새 서버 추가 = 패키지 생성, BaseMCPServer 확장, cli.ts에 등록.

빠른 시작

1. 설치 및 빌드

git clone https://github.com/your-org/mcp-tool-hub.git
cd mcp-tool-hub
npm install
npm run build

2. 구성

cp .env.example .env
# Edit .env with your paths and settings

3. 실행

# Via npm
npm run start --workspace=host

# Or directly
node host/dist/cli.js

4. 도구 호출

stdin으로 JSON을 보내고 stdout에서 JSON을 받습니다:

echo '{"toolName":"read_file","arguments":{"path":"hello.txt"}}' | node host/dist/cli.js

사용 가능한 도구

📁 파일 시스템 서버

모든 작업은 MCP_FS_ROOT로 샌드박스 처리됩니다. 경로 탐색(../)은 차단됩니다.

도구	설명
`read_file`	파일 내용 읽기 (utf8 또는 base64)
`write_file`	파일에 쓰기 또는 추가
`list_directory`	디렉토리 내용 나열 (선택적으로 재귀적)
`delete_file`	파일 삭제
`move_file`	파일 이동 또는 이름 변경
`get_file_info`	경로의 크기, 날짜 및 유형 가져오기

🔀 Git 서버

읽기 전용입니다. 쓰기 작업은 없습니다.

도구	설명
`git_log`	저장소 또는 파일의 커밋 기록
`git_show_file`	특정 커밋/브랜치에서의 파일 내용
`git_diff`	두 참조 간의 차이점
`git_status`	작업 트리 상태
`git_branches`	브랜치 나열 (로컬 + 선택적 원격)
`git_show_commit`	전체 커밋 세부 정보 및 차이점

🌐 Fetch 서버

MCP_FETCH_ALLOWED_DOMAINS를 통한 선택적 도메인 허용 목록을 지원합니다.

도구	설명
`fetch_url`	URL에서 HTML 또는 텍스트 가져오기
`fetch_json`	JSON API 응답 가져오기 및 파싱
`check_url`	URL에 도달 가능한지 확인 (HEAD 요청)

🧠 메모리 서버

재시작 후에도 유지됩니다. JSON 파일로 백업됩니다.

도구	설명
`memory_set`	키, 네임스페이스 및 태그와 함께 값 저장
`memory_get`	키로 값 검색
`memory_search`	모든 항목에 대한 전체 텍스트 검색
`memory_delete`	항목 삭제
`memory_list_namespaces`	개수가 포함된 모든 네임스페이스 나열
`memory_clear_namespace`	네임스페이스의 모든 항목 삭제

Ansible 배포

모든 클라이언트 머신에 동시에 배포하세요:

cd ansible

# First time
ansible-playbook -i inventory.yml deploy-mcp-hub.yml

# Update only (rebuild + restart)
ansible-playbook -i inventory.yml deploy-mcp-hub.yml --tags update

# Deploy to specific group
ansible-playbook -i inventory.yml deploy-mcp-hub.yml --limit servers

플레이북:

Node.js 20 설치 (없는 경우)
전용 mcp-hub 시스템 사용자 생성
프로젝트 복사 및 빌드
Ansible 변수에서 .env 구성 작성
systemd 서비스 설치 및 시작 (실패 시 자동 재시작)

inventory.yml의 호스트별 변수를 사용하면 머신 그룹마다 다른 허용 도메인, 로그 수준 및 경로를 구성할 수 있습니다.

새 서버 추가

주석이 포함된 전체 템플릿은 docs/adding-a-new-server.template.ts를 참조하세요.

요약하자면:

// 1. Create packages/server-myservice/src/my-server.ts
export class MyServer extends BaseMCPServer {
  constructor(options: MyOptions) {
    super(SERVER_INFO, options);
    this.registerTool("my_tool", this.handleMyTool.bind(this));
  }
  private async handleMyTool(args) {
    return this.ok({ result: "done" });
  }
}

// 2. Register in host/src/cli.ts
hub.use(new MyServer({ apiKey: process.env.MY_API_KEY! }));

아이디어: server-slack, server-postgres, server-docker, server-ansible, server-ssh, server-jira

환경 변수

변수	기본값	설명
`MCP_DATA_DIR`	`./mcp-data`	모든 허브 데이터의 루트
`MCP_FS_ROOT`	`./mcp-data/files`	파일 시스템 샌드박스 루트
`MCP_GIT_WORKSPACE`	`./mcp-data/repos`	Git 저장소 기본 경로
`MCP_MEMORY_PATH`	`./mcp-data/memory.json`	메모리 저장 파일
`MCP_FETCH_ALLOWED_DOMAINS`	(비어 있음 = 모두)	쉼표로 구분된 도메인 허용 목록
`MCP_LOG_LEVEL`	`info`	`debug	info	warn	error`

보안 참고 사항

파일 시스템: 엄격하게 샌드박스 처리됩니다. 경로 탐색 공격은 데이터가 아닌 오류를 반환합니다.
Git: 읽기 전용입니다. commit, push 또는 clone 작업이 노출되지 않습니다.
Fetch: 선택적 도메인 허용 목록은 내부 서비스에 대한 SSRF를 방지합니다.
Systemd 서비스: PrivateTmp=true 및 NoNewPrivileges=true를 사용하여 루트가 아닌 사용자로 실행됩니다.

요구 사항

Node.js ≥ 18 (네이티브 fetch API용)
Git (server-git용)
systemd가 있는 Linux (Ansible 배포용)

mcp-tool-hub