nanomcp

Dies ist eine minimale MCP-Demo, die ohne das MCP Python SDK von Hand geschrieben wurde. Sie umfasst die vollständige Kette:

1. nanomcp.server fungiert als MCP-Server und sendet/empfängt JSON-RPC über stdio.

2. nanomcp.cli fungiert als MCP-Client/Host, startet den Server und führt initialize, tools/list und tools/call aus.

3. Der chat-Befehl ruft OpenAI Chat Completions auf. Nachdem das Modell einen Funktions-/Tool-Aufruf zurückgibt, wandelt die CLI diesen in einen MCP tools/call um und sendet das Werkzeugergebnis zurück an das Modell, um die endgültige Antwort zu generieren.

Die Beziehung zwischen MCP und Funktionsaufrufen

Kurz gesagt: Funktionsaufrufe sind eine Modell-API-Fähigkeit, bei der „das Modell Ihrer Anwendung mitteilt, welche Funktion es aufrufen möchte“; MCP ist ein Verbindungsprotokoll, das festlegt, „wie Ihre Anwendung externe Tools/Kontextdienste über ein einheitliches Protokoll entdeckt und aufruft“.

Genauer gesagt:

• Funktions-/Tool-Aufrufe finden zwischen LLM API <-> Ihrer Anwendung statt. Das Modell führt die Funktion nicht wirklich aus, es gibt nur eine Aufrufabsicht wie {"name":"get_weather","arguments":{...}} zurück.

• MCP findet zwischen Ihrer Anwendung <-> MCP-Server statt. Der MCP-Server stellt eine Liste von Tools und Einstiegspunkte für die Ausführung bereit, wie z. B. tools/list und tools/call.

• Der Host/Client ist der Vermittler. Er ruft zuerst das Tool-Schema vom MCP-Server ab, wandelt diese Schemas in Tools für die Modell-API um; nachdem das Modell ein Tool ausgewählt hat, ruft der Host/Client den MCP-Server auf.

Die Kette in diesem Projekt ist:

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

Sie befinden sich also nicht auf derselben Ebene:

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

Related MCP server: MCP Server Demo

Dateistruktur

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 direkt ausführen, ohne das Modell aufzurufen

Führen Sie im Projektverzeichnis aus:

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

Direkter Aufruf des Wetter-Tools:

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

Direkter Aufruf des Tools für das aktuelle Datum und die Uhrzeit:

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

Direkter Aufruf des Dateisuch-Tools:

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

Standardmäßig wird nur ~/Desktop durchsucht. Sie können das Suchstammverzeichnis vorübergehend erweitern oder verkleinern:

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

Die vollständige Modell + MCP-Kette ausführen

Sie benötigen einen OpenAI API-Key. Hier wird nicht das OpenAI Python SDK verwendet, sondern die Standardbibliothek urllib, um HTTP-Anfragen direkt zu senden.

Es wird empfohlen, die lokale Konfiguration in .env zu schreiben:

cd ~/Desktop/nanomcp
cp .envtemplate .env

Bearbeiten Sie dann .env:

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

.env wird automatisch von der CLI gelesen und wurde bereits von .gitignore ignoriert.

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

Das Standardmodell ist gpt-4.1-mini. Sie können es ändern:

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

Wenn Sie ein OpenAI-kompatibles Gateway verwenden:

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

Leichte Überprüfung der lokalen Konfiguration und des MCP-Servers:

python3 -m nanomcp.cli doctor

Fehlerbehebung

Wenn chat OpenAI API quota is exhausted (429 insufficient_quota) ausgibt, bedeutet dies, dass die Modell-API die Anfrage abgelehnt hat: Das Projekt, zu dem der OPENAI_API_KEY gehört, hat kein verfügbares Guthaben oder die Abrechnung ist nicht aktiviert. Dies ist kein Fehler des MCP-Servers, da die Anfrage abgelehnt wurde, bevor das Modell einen Tool-Aufruf zurückgeben konnte.

Reihenfolge der Fehlerbehebung:

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

• Der erste Befehl zeigt maskiert die gültige Konfiguration an, ob die Shell .env überschreibt und ob der MCP-Server Tools auflisten kann.

• Der zweite Befehl bestätigt, ob der Key in der Shell bereits gesetzt ist.

• Der dritte Befehl bestätigt die lokale Konfiguration in .env.

• Der vierte Befehl überprüft, ob die lokale MCP-Kette normal funktioniert, ohne von der Modell-API abhängig zu sein.

• Der fünfte Befehl demonstriert, wie man auf ein OpenAI-kompatibles Gateway wechselt.

• Wenn Sie weiterhin die offizielle OpenAI-API verwenden, müssen Sie einen Key/ein Projekt mit Guthaben verwenden oder die Abrechnung und Modellberechtigungen überprüfen.

Optionales echtes Wetter

Das Standardwetter ist deterministische Demo-Daten, was das Erlernen der Protokollkette ohne Netzwerk oder Drittanbieter-Keys erleichtert. Um eine echte Abfrage auszuprobieren:

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

Das echte Wetter verwendet https://wttr.in und greift bei einem Fehler automatisch auf Demo-Daten zurück.

Testen

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

Testabdeckung:

• MCP initialize

• MCP tools/list

• MCP tools/call get_weather

• MCP tools/call find_files

• MCP tools/call get_current_datetime

Wichtige Beobachtungen

Sehen Sie sich openai_tools_from_mcp() in nanomcp/cli.py an: Es wandelt das MCP-Tool-Schema in das OpenAI-Funktions-Tool-Schema um.

Sehen Sie sich run_chat() an: Es ruft mcp.call_tool() auf, nachdem es tool_calls vom Modell erhalten hat. Dies ist der Verbindungspunkt zwischen MCP und Funktionsaufrufen.

Sehen Sie sich main() in nanomcp/server.py an: Es liest nur von stdin und schreibt nach stdout, wobei jede Zeile JSON-RPC ist. Der Server kennt OpenAI nicht und hat keinen direkten Kontakt zum Modell.