# MCP Router

로컬 stdio MCP 서버를 명령·작업 설명으로 검색하고 필요한 서버만 실행하는
allowlist 기반 MCP 어댑터입니다.

## 동작 방식

Codex에는 이 라우터 하나만 상시 등록합니다. 라우터는 작은 고정 도구 5개만
노출하며, 하위 MCP의 전체 도구 스키마는 `load_mcp`를 명시적으로 호출한 뒤에만
응답으로 반환합니다.

1. `search_mcp(query)`로 적합한 MCP를 검색합니다.
2. `load_mcp(name)`으로 하위 프로세스를 시작하고 도구 스키마를 받습니다.
3. `call_mcp(name, tool_name, arguments)`로 실제 도구를 호출합니다.
4. 작업 후 `unload_mcp(name)`으로 프로세스를 종료합니다.

추가로 `list_mcp()`는 등록 목록과 현재 로드 상태를 반환합니다.

## 보안 경계

- 모델이 레지스트리를 수정하는 도구는 제공하지 않습니다.
- `registry.yaml`에 등록된 절대 실행 파일만 시작합니다.
- 셸 문자열을 실행하지 않고 `command`와 `args` 배열을 직접 전달합니다.
- 기본 시스템 환경변수 외에는 `env`와 `inherit_env`에 선언된 값만 전달합니다.
- 비밀 값은 YAML에 저장하지 않고 `inherit_env`에 환경변수 이름만 등록합니다.
- 하위 MCP의 도구 이름도 로드 시 확인된 목록으로 제한합니다.

## 설치 및 검증

```powershell
cd <mcp-router-directory>
uv sync
uv run pytest
uv run ruff check .
```

## 실행

```powershell
uv run mcp-router
```

## Codex 등록

Codex 설정에는 하위 MCP 대신 라우터만 추가합니다.

```toml
[mcp_servers.mcp_router]
command = "C:\\path\\to\\mcp-router\\.venv\\Scripts\\mcp-router.exe"
cwd = "C:\\path\\to\\mcp-router"
```

## 레지스트리 확장

`registry.example.yaml`을 `registry.local.yaml`로 복사한 뒤 `servers` 아래에
항목을 추가합니다. `registry.local.yaml`은 Git에서 제외됩니다.

```yaml
servers:
  example:
    description: 수행하는 작업 설명
    keywords: [검색어, command phrase]
    command: C:\absolute\path\to\server.exe
    args: []
    cwd: C:\absolute\working\directory
    env:
      NON_SECRET_SETTING: value
    inherit_env:
      - SECRET_ENV_NAME
    load_timeout_seconds: 30
    call_timeout_seconds: 300
```

`command`와 `cwd`는 반드시 존재하는 절대 경로여야 합니다. 레지스트리 위치를
바꾸려면 라우터 프로세스에 `MCP_ROUTER_REGISTRY`를 설정합니다.

`docs/`, `scripts/`, `examples/`는 로컬 보조 자료로 기본 `.gitignore` 대상입니다.