UVG 로컬 MCP 서버

저자: Anggelie Velásquez — 학번 221181 과테말라 계곡 대학교 — 과정 CC3067

1. 설명

MCP(Model Context Protocol) 로컬 서버로, FastMCP나 공식 MCP SDK를 사용하지 않고 표준 Python 3로 처음부터 구현했습니다. 서버는 stdio를 통해 클라이언트와 통신하며, 수동으로 구현한 JSON-RPC 2.0을 사용합니다.

Related MCP server: @belal-elsabbagh-apex/copilot-mcp

2. 목표

해당 로직을 숨기는 라이브러리에 의존하지 않고 프로토콜을 수동으로 구축하여 MCP 서버의 수명 주기(initialize → notifications/initialized → tools/list → tools/call)에 대한 이해를 입증합니다.

3. 아키텍처

Cliente MCP  <-- stdio (stdin/stdout) -->  server.py
                                              │
                                    ┌─────────┴─────────┐
                                    │                    │
                                jsonrpc.py           tools.py
                          (formato JSON-RPC 2.0)  (herramientas)

• server.py: 진입점, stdin 읽기 루프 및 메서드 라우팅.

• jsonrpc.py: JSON-RPC 2.0 응답/오류 구성 및 기본 검증.

• tools.py: 도구의 중앙 집중식 등록(메타데이터 + 스키마 + 실행 함수).

4. 사용된 프로토콜

• 전송: stdio(표준 입력 / 표준 출력).

• 프레이밍: 줄당 하나의 JSON-RPC 2.0 메시지(JSON Lines / NDJSON). Content-Length 유형의 프레이밍은 사용하지 않습니다.

• 메시지 형식: JSON-RPC 2.0, 수동 구현(JSON-RPC 또는 MCP 라이브러리 없음).

• 보고된 MCP 프로토콜 버전: 2024-11-05(initialize 응답의 protocolVersion 필드).

• stdout은 오직 JSON-RPC 응답 전용으로 예약됩니다. 모든 로그는 stderr로 전송됩니다.

5. 구현된 MCP 메서드

다른 모든 메서드는 JSON-RPC 오류 -32601 Method not found를 반환합니다.

6. 사용 가능한 도구

analizar_texto

입력: { "texto": "Hola mundo" } 반환: 문자 수, 단어 수, 줄 수, 대문자 및 소문자 텍스트.

calcular_estadisticas

입력: { "numeros": [10, 20, 30, 40] } 반환: 개수, 합계, 평균, 최소값 및 최대값. numeros가 목록이고, 비어 있지 않으며, 숫자 값만 포함하는지 검증합니다.

informacion_sistema

인수 없음. 반환: 운영 체제, Python 버전, 플랫폼 및 현재 작업 디렉터리. 비밀번호, 토큰, 환경 변수 또는 파일 내용을 노출하지 않습니다.

7. 요구 사항

• Python 3.8 이상.

• 외부 종속성이 필요하지 않습니다(requirements.txt 참조).

8. 설치

git clone https://github.com/Anggelie/mcp-local-server-uvg.git
cd mcp-local-server-uvg

9. 서버를 수동으로 실행하는 방법

PowerShell에서 서버는 stdin을 통해 메시지를 기다립니다:

python src/server.py

예를 들어 JSON 한 줄을 작성하고 Enter를 누를 수 있습니다:

{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}

서버는 stdout에 JSON 한 줄로 응답합니다. 종료하려면 Ctrl+Z를 누른 다음 Enter를 누르세요(Windows에서 stdin 종료).

또한 예제 파일 전체를 한 번에 보낼 수 있습니다:

Get-Content examples/requests.jsonl | python src/server.py

10. 테스트 방법

자동 테스트(unittest)

python -m unittest discover tests -v

데모 클라이언트(하위 프로세스)

python examples/test_client.py

이 스크립트는 src/server.py를 하위 프로세스로 실행하고 3가지 도구에 대해 initialize -> initialized -> tools/list -> tools/call 주기를 자동으로 실행하며, 존재하지 않는 메서드의 경우도 포함합니다.

11. MCP 클라이언트에서 구성하는 방법

예제 구성이 client-config/claude_desktop_config.example.json에 포함되어 있습니다:

{
  "mcpServers": {
    "uvg-local-server": {
      "command": "python",
      "args": [
        "C:\\RUTA\\AL\\PROYECTO\\src\\server.py"
      ]
    }
  }
}

중요: C:\RUTA\AL\PROYECTO를 이 저장소를 복제한 실제 경로로 바꾸세요.

12. 예제

examples/requests.jsonl을 참조하세요. 이 파일에는 세 가지 도구에 대한 initialize, notifications/initialized, tools/list, tools/call을 다루는 줄별 JSON-RPC 메시지와 오류 사례가 포함되어 있습니다.

13. 프로젝트 구조

mcp-local-server-uvg/
│
├── src/
│   ├── server.py      # Punto de entrada del servidor
│   ├── jsonrpc.py      # Utilidades JSON-RPC 2.0
│   └── tools.py        # Registro de herramientas
│
├── tests/
│   ├── test_jsonrpc.py
│   └── test_tools.py
│
├── examples/
│   ├── requests.jsonl
│   └── test_client.py
│
├── client-config/
│   └── claude_desktop_config.example.json
│
├── .gitignore
├── requirements.txt
├── README.md
└── README_ES.md

14. 오류 처리

JSON-RPC 2.0 표준 코드가 구현되어 있습니다: