MCP Agent Homework

MCP_HOMEWORK_SKILL.md의 과제를 위해 만든 TypeScript MCP(Model Context Protocol) 시스템입니다: Agent Host는 Agent Skill(SKILL.md)을 로드하고, 필수 세 가지 전송 방식을 모두 통해 세 개의 MCP 서버에 연결하며, 각 서버의 도구를 발견/집합한 다음 Gemini이 올바른 서버에서 올바른 도구를 선택하고 호출할 수 있게 합니다.

아키텍처

                          Agent Host (src/host)
                     skill-loader + connection-manager
                       + tool-bridge + gemini-client
                                 |
              +------------------+------------------+
              |                  |                   |
              v                  v                   v
        stdio server       local HTTP server    public HTTP server
     (src/servers/stdio-  (src/servers/http-   (same http-server.ts,
        server.ts)          server.ts, no auth)   API-key protected)
              |                  |                   |
              +------------------+-------------------+
                                 |
              shared tool logic (src/servers/shared/tools.ts)
       3 tools (calculator, text_stats, unit_convert) + 1 resource + 1 prompt

• src/servers/shared/tools.ts — 3개 도구, 1개 리소스, 1개 프롬프트의 단일 구현입니다. 모든 서버에 동일하게 등록되어 어디서든 같은 로직을 재사용합니다(중복된 비즈니스 로직 없음).

• src/servers/stdio-server.ts — stdio 기반 MCP(자식 프로세스로 실행됨).

• src/servers/http-server.ts — Streamable HTTP 기반 MCP. 동일한 파일/코드가 "로컬" 서버와 "공개" 서버 양쪽에서 실행되며, 유일한 차이는 구성(PORT, PUBLIC_MCP_API_KEY)입니다.

• src/host/connection-manager.ts — MCP Host: 구성된 모든 서버에 연결하고, 도구/리소스/프롬프트를 발견하며, 충돌을 방지하기 위해 도구 이름을 <namespace>__<tool>로 네임스페이스화하고, 도구 호출을 해당 소유 서버로 되돌려 디스패치합니다.

• src/host/tool-bridge.ts — 발견된 MCP 도구를 Gemini 함수 선언으로 변환합니다.

• src/host/gemini-client.ts — Gemini 도구 호출 루프(메시지 전송 → 함수 호출 읽기 → 연결 관리자를 통한 디스패치 → 함수 응답 전송 → 최종 텍스트가 나올 때까지 반복).

• src/host/skill-loader.ts — SKILL.md을 로드하여 모델의 시스템 지시문(system instruction)으로 주입하므로, 스킬이 도구 사용 방식을 능동적으로 형성합니다.

• src/host/agent-host.ts — config/servers.json에서 위 요소들을 서로 연결합니다.

• src/host/cli.ts — CLI 진입점(대화형 또는 --demo).

Related MCP server: mcp-tools-server

준비(Setup)

npm install

비밀값은 api.env(이미 gitignore 처리됨)에 보관합니다:

API_KEY=your-gemini-api-key
# Optional, only needed once you deploy the public server:
# PUBLIC_MCP_URL=https://your-app.onrender.com/mcp
# PUBLIC_MCP_API_KEY=some-strong-random-key

각 구성 요소 실행하기

stdio 서버 (20점)

npm run server:stdio            # run directly
npm run inspector:stdio         # open MCP Inspector against it

Inspector는 3개의 도구(calculator, text_stats, unit_convert), 1개의 리소스(docs://unit-conversions), 1개의 프롬프트(explain-tool-result)를 발견하며, 모두 실행/읽을 수 있습니다.

로컬 HTTP 서버

npm run server:http             # listens on http://127.0.0.1:8787/mcp, no auth
npm run inspector:http          # then connect Inspector to that URL

공개 HTTP 서버 (15점)

PUBLIC_MCP_API_KEY가 설정되면 동일한 http-server.ts가 "공개" 서버가 됩니다. 이 시점부터 모든 요청은 일치하는 x-api-key 헤더를 필요로 하며, 키가 없거나 잘못된 경우 401 Unauthorized를 받게 됩니다.

$env:PORT=8788; $env:PUBLIC_MCP_API_KEY="a-strong-secret"; npm run server:http

공개 배포(Render.com, 포함된 render.yaml 사용):

1. git init && git add -A && git commit -m "MCP homework"를 실행한 뒤, 본인 소유의 GitHub 저장소로 푸시합니다.

2. Render에서: New + → Blueprint → 저장소를 선택합니다(render.yaml을 자동으로 읽음). 또는 Web Service를 수동으로 생성합니다:

   • Build command(빌드 명령): npm install && npm run build

   • Start command(시작 명령): npm run start:http

   • Health check path(헬스 체크 경로): /health

3. Render 대시보드에서 PUBLIC_MCP_API_KEY 환경 변수를 강력한 비밀값으로 설정합니다(절대 커밋하지 마세요).

4. 배포가 완료되면 생성된 URL과 키를 api.env에 넣습니다: PUBLIC_MCP_URL=https://<your-service>.onrender.com/mcp, PUBLIC_MCP_API_KEY=<same secret>.

5. Inspector로 검증합니다:

   • 키 없음 → 거부됨: curl -X POST https://<url>/mcp -H "Content-Type: application/json" -d "{...}"의 결과가 401.

   • 키 있음 → 정상 동작: npx @modelcontextprotocol/inspector --cli <url> --method tools/list에 --header "x-api-key: <secret>"을 전달합니다.

Agent Host

npm run agent          # interactive CLI
npm run agent:demo      # runs a scripted set of demo queries

시작 시 호스트는:

1. SKILL.md을 시스템 지시문으로 로드합니다.

2. config/servers.json을 읽고, stdio 서버(자동 생성됨), 로컬 HTTP 서버(이미 실행 중이어야 함), 공개 HTTP 서버(PUBLIC_MCP_URL/PUBLIC_MCP_API_KEY가 설정되어 있지 않으면 자동으로 건너뜀 — 공개 서버는 선택 사항이므로 라이브 배포 없이도 데모가 동작)에 연결합니다.

3. 모든 도구를 발견하고 네임스페이스화하여 Gemini에 넘긴 뒤, Gemini이 요청한 각 도구 호출을 올바른 MCP 서버로 디스패치합니다.

구성

서버 등록은 config/servers.json을 통한 데이터 기반으로 이루어집니다 — 호스트 코드를 수정하는 대신 해당 파일에서 서버를 추가/삭제하면 됩니다. url 값 안의 ${VAR}은 연결 시점에 process.env에서 해석되며, apiKeyEnv는 해당 값이 x-api-key로 전송되는 환경 변수의 이름을 지정합니다.

Agent Skill

SKILL.md는 에이전트에게 산술/단위 변환/텍스트 통계를 추측하는 대신 도구 호출을 선호하도록 하고, 논리적 요청마다 네임스페이스된 도구 하나를 선택하며, 지원되는 변환에 대해 확신이 없을 때 docs://unit-conversions 리소스를 참고하고, 결과를 평이한 언어로 설명하도록 지시합니다. 이 스킬은 실행 시마다 Gemini 시스템 지시문에 그대로(verbatim) 로드되므로(src/host/skill-loader.ts 참조), 해당 규칙이 도구 선택과 응답 스타일에 직접 영향을 줍니다 — 데모 출력에서 확인할 수 있습니다(예: 에이전트는 산수를 직접 계산하지 않고 항상 도구를 호출합니다).

보안 참고 사항

• 비밀값은 커밋되지 않습니다. api.env는 gitignore 처리되어 있고, 공개 서버는 환경에서 PUBLIC_MCP_API_KEY만 읽습니다.

• 공개 HTTP 서버는 일치하는 x-api-key 헤더가 없는 요청을 401으로 거부하며, 유효한 키가 제공된 요청만 수락합니다.