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 が属するプロジェクトに利用可能なクォータがないか、課金が有効になっていません。これは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サーバーがツールをリストできるかをマスクして表示します。

• 2番目のコマンドは、シェルでキーが設定されているかを確認します。

• 3番目のコマンドは、.env 内のローカル設定を確認します。

• 4番目のコマンドは、モデルAPIに依存せず、ローカルのMCPリンクが正常かどうかを検証します。

• 5番目のコマンドは、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を知らず、モデルにも直接触れません。