mcp-agent-toolkit

ライブデモ: 未デプロイ — agent.build-with-deepak.com にて計画中。 このリポジトリは完成しており、ローカルで検証済みです（ビルド、lint、25件のユニットテスト — 実際のMCPプロトコルのラウンドトリップを含む — および5件のe2eテスト）。まだデプロイされておらず、実際のOllama/Postgresに対して実行されていません。ステータスを参照してください。

問題

ほとんどの「AIエージェント」デモは、自律性を装った単一の隠れたツール呼び出しです。これはその仕組みを示します: 3つの実ツールを持つModel Context Protocolエージェント — 読み取り専用のPostgreSQLコマースデータベース、ライブ天気API、電卓 — が、実際に複数のツールを必要とする質問に答えます（「ドバイの顧客からの総収益と、そこの天気は？」）。すべてのツール呼び出し、その引数、結果、レイテンシ、そして — 重要なことに — その失敗とモデルによる回復が、発生時に画面にストリーミングされます。

Related MCP server: MCP Tool Server

試す

デモアカウントで続行は、実際のAPIに対して実際の2時間セッションを発行します — 同じエージェント、同じツール、同じデータ。サンプルデータベースは共有され読み取り専用であるため、デモセッションにはユーザーごとのクリーンアップは不要です: 訪問者が何をしても書き込むことはできません。登録（永続的なユーザーごとのデータ）は進行中です。登録ボタンとPOST /api/auth/register（501）はどちらも正直にその旨を伝えます。

アーキテクチャ

flowchart TB
    subgraph Browser
        UI[Angular SPA<br/>login → live tool-call timeline]
    end

    subgraph VPS -- host nginx, TLS
        Nginx[nginx :443]
    end

    subgraph "Docker Compose stack"
        Web[web container]
        subgraph API [api container — NestJS]
            Loop[Agent loop]
            Client[MCP Client]
            Server[MCP Server]
        end
        PG[(PostgreSQL<br/>sample dataset<br/>mcp_readonly role)]
    end

    Ollama[Ollama llama3.1 — on the VPS]
    Meteo[Open-Meteo API]

    UI -->|HTTPS| Nginx --> Web -->|/api/*| Loop
    Loop -->|chat + tools| Ollama
    Loop -->|listTools / callTool| Client
    Client <-->|MCP protocol, in-memory transport| Server
    Server -->|query_database| PG
    Server -->|get_weather| Meteo
    Server -->|calculate| Server

ループ: モデルは質問とMCPで発見されたツールスキーマを受け取る → ツール呼び出しを生成 → 各呼び出しはMCPクライアントを通じて実行 → 結果（エラーを含む）はモデルに戻る → 散文で答えるかステップ上限（デフォルト6）に達するまで繰り返す。すべてのホップはSSEイベントです。

主要な決定とトレードオフ

1つのプロセス内の実際のMCPサーバーとクライアント。 ツールは単純な関数でもよかった — プロトコル境界がポイントです。エージェントループはMCPクライアントとのみ通信します: listTools()でツールを発見し、callTool()で呼び出します。これは外部サーバーに対してstdioやHTTPで行うのとまったく同じです。ツールをこのプロセスから移動するには、トランスポートの1行を変更するだけで、エージェントは変更不要です。インメモリトランスポートにより、単一VPSデモは追加ポートやサブプロセス監視を不要にしつつ、SDKは両方向でスキーマを検証します — ユニットスイートはその実際のハンドシェイクをテストしており、モックではありません。

SQLインジェクションはエッジケースではなくデフォルト状態として扱う。 エージェントは見知らぬ人の自然言語の質問からSQLを書きます — これは構造上、信頼できない入力です。2つのレイヤー: アプリ側ガード（sql-guard.ts: コメント除去、単一ステートメント、SELECT/WITHのみ、set_configがsetではないことを認識するキーワード拒否リスト、結果を100行に制限するサブクエリラップ）は、モデルが対処できるメッセージで迅速に失敗します。その下では、クエリは専用のmcp_readonly Postgresロールとして実行されます — SELECTのみの権限、default_transaction_read_only=on、5秒のステートメントタイムアウト — これはガードにバグがあっても保持されます。ガード自身のテストは、その許容される字句上の制限を文書化しています。

ツールエラーは失敗として表面化させず、モデルにフィードバックする。 失敗したツール呼び出しはisError結果として返され、ツール出力として会話に入ります。モデルはエラーを読み、SQLを修正するか別の都市を選び、再試行します — UIはまさにそのことを注釈します（「エラーはモデルに戻る — 次のステップを見てください」）。回復を見ることは、決して失敗しないことよりも、エンジニアリングの証拠として価値があります。

電卓は60行のパーサーであり、evalではない。 LLMが書いた式を任意のJavaScript評価器に渡すと、電卓がコード実行ツールになります。明示的な文法による再帰下降は、退屈だが正しい代替手段です。そのテストには1 + 1; process.exit()が含まれます。

ループステップは非ストリーミング。タイムラインがストリームです。 モデルの応答がツール呼び出しなのか最終回答なのかは、完了したときにのみわかります。また、ツール呼び出しの応答は短いです。ライブでストリーミングされるのは、実際に興味深いもの — ツール呼び出しと結果が発生する様子 — です。最終的な散文の回答は1つのイベントとして到着します。（同じSSE-over-POSTトランスポートの決定は、兄弟ルーターデモと同じ理由です。）

天気にはOpen-Meteo。 無料でキー不要: サードパーティAPIキーを含む無人公開デモは、漏洩待ちの事故であり、請求が発生するのを待つものです。トレードオフ — SLAなし — は、天気ツールの障害自体がエラーハンドリングパスのライブデモになるため、許容できます。

固定IDを持つ固定サンプルデータセット。 シーディングはON CONFLICT DO NOTHINGを使用するため、毎回の起動で重複が蓄積される代わりに、同じ15顧客/12製品/32注文に収束します。都市は、DBと天気の質問が自然に構成されるように選ばれました（ドバイ、ニューデリー、ロンドン…）。

データベースのセットアップとリセット

スキーマ、サンプルデータ、mcp_readonlyロールの権限はapps/api/db/schema.sqlにあり、APIの起動ごとに冪等に適用されます。ロール自体（パスワードはMCP_READONLY_PASSWORDから）は、CREATE ROLEがパラメータ化されたパスワードを受け取れないため、db.service.tsで作成されます。pnpm db:resetはサンプルテーブルを削除します。次の起動で全てが再作成されます。ここには定期的なデモデータのクリーンアップは意図的にありません — 訪問者は書き込めないからです。

100倍スケールで変更する点

インメモリMCPトランスポートが最初に移動するものです: 実際のマルチテナントツールサーバーは別のサービス（stdioサブプロセスまたはHTTP）として実行され、プロトコル境界でツールごとの認可と監査ログが行われます — このコードベースはすでにその交換に向けて形作られています。エージェントループは、永続的な会話（セッションでキー付けされたconversationsテーブル — 登録アカウントの自然な最初の機能）、独立した呼び出しでの並列ツール実行、ステップ上限に加えたトークンバジェット上限を獲得するでしょう。そしてSQLツールは生のSELECTを完全に公開するのをやめるでしょう: スケールでは、名前付きのパラメータ化されたクエリテンプレートを公開し、モデルにパラメータを埋めさせます — ここでのガードプラス読み取り専用ロールのパターンは、そのアイデアのデモサイズ版であり、代替ではありません。

ローカルセットアップ

Node 22以上、pnpm。フル体験には、Postgresとツール対応モデルを持つOllama（ollama pull llama3.1:8b — 通常のllama3はツール呼び出しを確実に生成しません）。

corepack enable && pnpm install
pnpm dev:api   # :3000
pnpm dev:web   # :4200, proxies /api → :3000

ゲートチェック:

pnpm --filter api build && pnpm --filter api lint && pnpm --filter api test && pnpm --filter api test:e2e
pnpm --filter web build && pnpm --filter web test

VPSへのデプロイ

1. cp .env.example .env — POSTGRES_PASSWORD、MCP_READONLY_PASSWORD、JWT_SECRETを設定します（composeはこれらなしでは起動を拒否します）。VPSでollama listがllama3.1:8bを示すことを確認します。

2. docker compose up -d --build — webは127.0.0.1:8092のみにバインドします。

3. nginx/agent.build-with-deepak.com.confをホストのnginxにインストールし、certbot --nginx -d agent.build-with-deepak.comを実行します。

4. GET /api/healthが未認証の生存確認プローブです。

ステータス

• SDKのインメモリトランスポート上の実際のMCPサーバー+クライアント、3つのツール、テストでカバーされたプロトコルラウンドトリップ

• ライブSSEツール呼び出しタイムライン、エラー回復フィードバック、ステップ上限を備えたエージェントループ

• 2層SQL保護（ガード+専用読み取り専用Postgresロール）

• デモアカウント認証のエンドツーエンド。登録は正直な501近日公開

• ビルド、lint、全テスト合格（API: ユニット25 + e2e 5、web: 6）

• ライブOllama/Postgresに対してまだ実行されていません — この環境にはどちらもありませんでした。特にエージェントループのOllamaツール呼び出しパスは、これを誰かの前に出す前に実際のllama3.1実行が必要です

• まだデプロイされていません

• 登録/永続アカウント — 進行中（設計上デモ優先）