nanomcp

이것은 MCP Python SDK 없이 직접 작성한 최소한의 MCP 데모입니다. 전체 링크를 포함합니다:

1. nanomcp.server는 MCP 서버로서 stdio를 통해 JSON-RPC를 송수신합니다.

2. nanomcp.cli는 MCP 클라이언트/호스트로서 서버를 시작하고 initialize, tools/list, tools/call을 수행합니다.

3. chat 명령어는 OpenAI Chat Completions를 호출합니다. 모델이 function/tool call을 반환하면, CLI는 이를 MCP tools/call로 변환하고, 도구 결과를 다시 모델에 보내 최종 답변을 생성합니다.

MCP와 function call의 관계

한 문장으로 요약하자면: function call은 "모델이 당신의 애플리케이션에 어떤 함수를 호출하고 싶은지 알려주는" 모델 API 기능이며, MCP는 "당신의 애플리케이션이 통합된 프로토콜을 사용하여 외부 도구/컨텍스트 서비스를 발견하고 호출하는 방법"을 정의하는 연결 프로토콜입니다.

더 구체적으로 설명하면:

• Function/tool calling은 LLM API <-> 당신의 애플리케이션 사이에서 발생합니다. 모델은 실제로 함수를 실행하지 않으며, {"name":"get_weather","arguments":{...}}와 같은 호출 의도만 반환합니다.

• MCP는 당신의 애플리케이션 <-> MCP 서버 사이에서 발생합니다. MCP 서버는 tools/list 및 tools/call과 같은 도구 목록과 실행 진입점을 노출합니다.

• 호스트/클라이언트는 중개자입니다. 먼저 MCP 서버에서 도구 스키마를 가져와 모델 API의 도구로 변환합니다. 모델이 도구를 선택하면 호스트/클라이언트는 MCP 서버를 호출합니다.

본 프로젝트의 링크는 다음과 같습니다:

用户问题
  -> nanomcp.cli
  -> OpenAI Chat Completions tools=function schemas
  <- 模型返回 tool_calls
  -> nanomcp.cli 把 tool_call 映射为 MCP tools/call
  -> nanomcp.server 执行 get_weather 或 find_files
  <- MCP tool result
  -> nanomcp.cli 把结果发回模型
  <- 模型最终回答

따라서 이들은 같은 계층이 아닙니다:

Function call: 模型 API 的工具选择/参数生成机制
MCP: 应用连接工具服务器的标准协议

Related MCP server: MCP Server Demo

파일 구조

nanomcp/
  nanomcp/
    cli.py       # MCP client + model caller
    server.py    # hand-written MCP server over stdio
  tests/
    test_protocol.py
  pyproject.toml
  README.md

모델 호출 없이 MCP 직접 실행

프로젝트 디렉토리에서 다음을 실행하세요:

cd ~/Desktop/nanomcp
python3 -m nanomcp.cli list-tools

날씨 도구 직접 호출:

python3 -m nanomcp.cli call get_weather '{"location":"Shanghai","unit":"celsius"}'

현재 날짜 및 시간 도구 직접 호출:

python3 -m nanomcp.cli call get_current_datetime '{"timezone":"Asia/Shanghai"}'

파일 찾기 도구 직접 호출:

python3 -m nanomcp.cli call find_files '{"query":"*.pdf","max_results":5}'

기본적으로 ~/Desktop만 검색합니다. 검색 루트 디렉토리를 일시적으로 확장하거나 축소할 수 있습니다:

NANOMCP_FILE_ROOT=~/Desktop/nanomcp python3 -m nanomcp.cli call find_files '{"query":"*.py"}'

전체 모델 + MCP 링크 실행

OpenAI API 키가 필요합니다. 여기서는 OpenAI Python SDK를 사용하지 않고 표준 라이브러리 urllib을 사용하여 HTTP를 직접 전송합니다.

로컬 설정을 .env에 작성하는 것을 권장합니다:

cd ~/Desktop/nanomcp
cp .envtemplate .env

그런 다음 .env를 편집하세요:

OPENAI_API_KEY=你的 key
OPENAI_BASE_URL=https://api.openai.com/v1
NANOMCP_MODEL=gpt-4.1-mini
NANOMCP_TIMEZONE=Asia/Shanghai

.env는 CLI에 의해 자동으로 읽히며, 이미 .gitignore에 포함되어 있습니다.

cd ~/Desktop/nanomcp
python3 -m nanomcp.cli chat "上海今天天气怎么样？顺便帮我找桌面上的 PDF 文件"

기본 모델은 gpt-4.1-mini입니다. 변경할 수 있습니다:

NANOMCP_MODEL=gpt-5-mini python3 -m nanomcp.cli chat "找一下这个项目里的 py 文件"

OpenAI 호환 게이트웨이를 사용하는 경우:

OPENAI_BASE_URL=http://localhost:8000/v1 python3 -m nanomcp.cli chat "上海天气怎么样？"

로컬 설정 및 MCP 서버에 대한 가벼운 점검:

python3 -m nanomcp.cli doctor

문제 해결

chat 출력에 OpenAI API quota is exhausted (429 insufficient_quota)가 표시되면, 모델 API가 요청을 거부했음을 의미합니다. 현재 OPENAI_API_KEY가 속한 프로젝트에 사용 가능한 할당량이 없거나 결제가 활성화되지 않았습니다. 이는 모델이 tool call을 반환하기 전에 요청이 거부된 것이므로 MCP 서버 실패가 아닙니다.

점검 순서:

python3 -m nanomcp.cli doctor
echo "$OPENAI_API_KEY"
cat .env
python3 -m nanomcp.cli call get_weather '{"location":"Shanghai"}'
OPENAI_BASE_URL=http://localhost:8000/v1 python3 -m nanomcp.cli chat "上海天气怎么样？"

• 첫 번째 명령어는 유효한 설정, 셸이 .env를 덮어쓰는지 여부, MCP 서버가 도구를 나열할 수 있는지 여부를 마스킹하여 표시합니다.

• 두 번째 명령어는 셸에 키가 설정되어 있는지 확인합니다.

• 세 번째 명령어는 .env의 로컬 설정을 확인합니다.

• 네 번째 명령어는 모델 API에 의존하지 않고 로컬 MCP 링크가 정상인지 확인합니다.

• 다섯 번째 명령어는 OpenAI 호환 게이트웨이로 전환하는 방법을 보여줍니다.

• 여전히 OpenAI 공식 API를 사용하는 경우, 할당량이 있는 키/프로젝트로 교체하거나 결제 및 모델 권한을 확인해야 합니다.

실제 날씨 사용(선택 사항)

기본 날씨는 네트워크나 타사 키가 없을 때 프로토콜 링크를 학습하기 편리하도록 결정론적 데모 데이터를 사용합니다. 실제 조회를 시도하려면:

NANOMCP_LIVE_WEATHER=1 python3 -m nanomcp.cli call get_weather '{"location":"Shanghai"}'

실제 날씨는 https://wttr.in을 사용하며, 실패 시 자동으로 데모 데이터로 대체됩니다.

테스트

cd ~/Desktop/nanomcp
python3 -m unittest discover -s tests

테스트 범위:

• MCP initialize

• MCP tools/list

• MCP tools/call get_weather

• MCP tools/call find_files

• MCP tools/call get_current_datetime

주요 관찰 사항

nanomcp/cli.py의 openai_tools_from_mcp()를 확인하세요: MCP 도구 스키마를 OpenAI 함수 도구 스키마로 변환합니다.

run_chat()을 확인하세요: 모델의 tool_calls를 수신한 후 mcp.call_tool()을 호출합니다. 이것이 MCP와 function call의 연결 지점입니다.

nanomcp/server.py의 main()을 확인하세요: stdin을 읽고 stdout에 쓰기만 하며, 각 줄은 JSON-RPC입니다. 서버는 OpenAI를 알지 못하며 모델에 직접 접근하지도 않습니다.