nanomcp

Esta es una demostración mínima de MCP escrita a mano sin el SDK de Python de MCP. Contiene el flujo completo:

1. nanomcp.server actúa como servidor MCP, enviando y recibiendo JSON-RPC a través de stdio.

2. nanomcp.cli actúa como cliente/host MCP, inicia el servidor y realiza initialize, tools/list y tools/call.

3. El comando chat invoca las Chat Completions de OpenAI. Después de que el modelo devuelve una llamada a función/herramienta, la CLI la convierte en una tools/call de MCP y luego envía el resultado de la herramienta de vuelta al modelo para generar la respuesta final.

Relación entre MCP y function call

En resumen: function call es la capacidad de la API del modelo para que "el modelo le diga a tu aplicación qué función quiere llamar"; MCP es el protocolo de conexión para que "tu aplicación descubra y llame a herramientas externas/servicios de contexto mediante un protocolo unificado".

Más específicamente:

• Function/tool calling ocurre entre LLM API <-> tu aplicación. El modelo no ejecuta realmente la función, solo devuelve una intención de llamada como {"name":"get_weather","arguments":{...}}.

• MCP ocurre entre tu aplicación <-> servidor MCP. El servidor MCP expone una lista de herramientas y puntos de entrada de ejecución, como tools/list y tools/call.

• El host/cliente es el intermediario. Primero obtiene el esquema de herramientas del servidor MCP y convierte estos esquemas en herramientas de la API del modelo; después de que el modelo selecciona una herramienta, el host/cliente llama al servidor MCP.

El flujo en este proyecto es:

用户问题
  -> 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 把结果发回模型
  <- 模型最终回答

Por lo tanto, no están en el mismo nivel:

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

Related MCP server: MCP Server Demo

Estructura de archivos

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

Ejecutar MCP directamente, sin llamar al modelo

Ejecuta en el directorio del proyecto:

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

Llamar directamente a la herramienta de clima:

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

Llamar directamente a la herramienta de fecha y hora actual:

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

Llamar directamente a la herramienta de búsqueda de archivos:

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

Por defecto, solo busca en ~/Desktop. Puedes ampliar o reducir temporalmente el directorio raíz de búsqueda:

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

Ejecutar el flujo completo de modelo + MCP

Se requiere una clave de API de OpenAI. Aquí no se utiliza el SDK de Python de OpenAI, sino que se envía HTTP directamente mediante la biblioteca estándar urllib.

Se recomienda escribir la configuración local en .env:

cd ~/Desktop/nanomcp
cp .envtemplate .env

Luego edita .env:

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

.env será leído automáticamente por la CLI y ya ha sido ignorado por .gitignore.

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

El modelo por defecto es gpt-4.1-mini. Puedes cambiarlo:

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

Si utilizas una pasarela compatible con OpenAI:

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

Verificación ligera de la configuración local y el servidor MCP:

python3 -m nanomcp.cli doctor

Solución de problemas

Si chat muestra OpenAI API quota is exhausted (429 insufficient_quota), significa que la API del modelo rechazó la solicitud: el proyecto al que pertenece la OPENAI_API_KEY actual no tiene cuota disponible o la facturación no está activada. Esto no es un fallo del servidor MCP, ya que la solicitud fue rechazada antes de que el modelo devolviera la llamada a la herramienta.

Orden de verificación:

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 "上海天气怎么样？"

• El primer comando muestra de forma segura la configuración válida, si el shell sobrescribe .env y si el servidor MCP puede listar las herramientas.

• El segundo comando confirma si la clave ya está configurada en el shell.

• El tercer comando confirma la configuración local en .env.

• El cuarto comando verifica si el flujo MCP local es normal, sin depender de la API del modelo.

• El quinto comando demuestra cómo cambiar a una pasarela compatible con OpenAI.

• Si aún utilizas la API oficial de OpenAI, necesitas cambiar a una clave/proyecto con cuota, o verificar la facturación y los permisos del modelo.

Clima real opcional

El clima por defecto es un dato de demostración determinista, conveniente para aprender el flujo del protocolo sin red o claves de terceros. Para probar una consulta real:

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

El clima real utiliza https://wttr.in, y volverá automáticamente a los datos de demostración en caso de fallo.

Pruebas

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

Cobertura de pruebas:

• MCP initialize

• MCP tools/list

• MCP tools/call get_weather

• MCP tools/call find_files

• MCP tools/call get_current_datetime

Observaciones clave

Observa openai_tools_from_mcp() en nanomcp/cli.py: convierte el esquema de herramientas de MCP al esquema de funciones de OpenAI.

Observa run_chat(): llama a mcp.call_tool() después de recibir tool_calls del modelo. Este es el punto de conexión entre MCP y function call.

Observa main() en nanomcp/server.py: solo lee stdin y escribe en stdout, cada línea es un JSON-RPC. El servidor no conoce OpenAI ni interactúa directamente con el modelo.