使用说明

mcp客户端后端

Gemini API + MCP (Model Context Protocol) 集成工具调用AI 代理后端服务器。

📖 概要

此项目包括：Google Gemini API 和MCP 使服务器协同工作，以满足用户的自然语言请求MCP 自动选择和运行工具并返回结果FastAPI 是基本的后端。

主要特征

🤖 智能工具选择: Gemini API 分析用户的要求MCP 自动选择工具
🔄 重复执行：如果搜索结果为0，则尝试使用其他关键字自动重新搜索
🔍 多关键字搜索：从一个请求中提取多个相关关键字，分别搜索
📊 自动获取详细信息：自动获取补贴详细信息（如果有搜索结果）
🌐 通用设计：支持不同领域的补贴搜索

主要用途

搜索补贴MCP 服务器协作）
其他MCP 利用工具的信息取得·处理

🏗️ 系统体系结构

┌─────────────┐
│   Client    │ (Flutter / curl / フロントエンド)
└──────┬──────┘
       │ HTTP POST /chat
       ▼
┌─────────────────────────────────────┐
│         FastAPI Server              │
│  (server.py)                        │
│  - /healthz: ヘルスチェック        │
│  - /tools: ツール一覧取得           │
│  - /chat: メインエンドポイント      │
└──────┬──────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────┐
│           Agent                      │
│  (mcp_agent/agent.py)                │
│  統括・統合処理                      │
│  ┌─────────────────────────────┐   │
│  │ 反復的な実行ループ            │   │
│  │ 1. 計画生成                   │   │
│  │ 2. ツール実行                 │   │
│  │ 3. 結果評価                   │   │
│  │ 4. 必要に応じて再実行         │   │
│  └─────────────────────────────┘   │
└───┬─────────────────────────────────┘
    │
    ├─► ConnectionManager ──► MCP Server (Jグランツ等)
    │   (ツール一覧取得・ツール実行)
    │
    ├─► TaskManager ──► Gemini API
    │   (実行計画生成・前回結果を考慮)
    │
    ├─► TaskExecutor ──► MCP Server
    │   (ツール実行・結果収集)
    │
    └─► Gemini API
        (最終回答生成)

🔄 处理流程（详细信息）

1.请求接收

用户以自然语言发送问题

POST /chat
{
  "message": "東京都のITツール導入補助金を探してください"
}

2.重复执行循环

代理最多重复5次以下循环：

while iteration < max_iterations:
    # 2-1) 実行計画の生成
    plan = task_manager.plan(
        message=message,
        tools=tools,
        previous_results=all_tool_results  # 前回の結果を考慮
    )

    # 2-2) ツール実行
    exec_result = task_executor.execute(plan)

    # 2-3) 継続判断
    if not should_continue_iteration(exec_result):
        break

继续判断示例：

0个搜索结果-用其他关键字重新搜索
有搜索结果-获取详细信息
收集了足够的信息→循环结束

3. 実行計画の生成（TaskManager）

Gemini API 发送以下信息：

请求用户
可用工具列表
上次运行结果（重复执行时）

Gemini 的JSON 形式返回执行计划：

{
  "tool_calls": [
    {
      "server": "jgrants",
      "tool": "search_subsidies",
      "arguments": {
        "keyword": "ITツール導入",
        "target_area_search": "東京都"
      },
      "reason": "ユーザーの要求に合致する補助金を検索"
    }
  ]
}

4.工具执行器

按照计划MCP 依次运行工具并收集结果

5.最终回答生成

所有工具运行结果Gemini 给，生成用日语易懂的回答

🧩 主要组件

1. `server.py` - FastAPI 应用程序

FastAPI 应用程序的入口点。

端点：

GET /healthz：健康检查
GET /tools：可用MCP 返回工具列表
POST /chat：接收用户的自然语言消息并执行代理处理

2. `mcp_agent/agent.py` - Agent（代理主机）

进行整体统一、统一的代理主体。

主要功能：

管理迭代执行循环
评估和继续确定工具运行结果
生成最终回答

处理流程：

ConnectionManager 的MCP 获取工具列表
迭代循环开始
- TaskManager 生成执行计划（考虑上次结果）
- TaskExecutor 的MCP 运行工具
- 评估结果并确定是否继续
基于所有工具结果Gemini 生成最终回答

3. `mcp_agent/task_manager.py` - TaskManager（実行計画生成）

MCP 生成工具执行计划的类。

特徴：

Gemini API 使用生成执行计划
考虑上次的执行结果制定以下计划
指示单独搜索多个关键字
通用提示设计（不依赖于特定用例）

提示设计要点：

每个关键字都作为单独的搜索运行
use_purpose 等参数不是必需的
如果搜索结果为0，则使用更常见的关键字重新搜索

4. `mcp_agent/task_executor.py` - TaskExecutor（工具运行）

按照执行计划MCP 依次运行工具。

机能：

TaskStep 的列表，按顺序执行
收集每个工具的运行结果
记录执行跟踪（为什么使用了哪个工具）

5. `mcp_agent/connection_manager.py` - ConnectionManager（MCP接続管理）

MCP 负责与服务器的连接和通信。

机能：

MCP 单击功能区上JSON-RPC 2.0 通信
获取工具列表（tools/list)
工具运行（tools/call)
SSE (Server-Sent Events) 格式响应

6. `mcp_agent/config_manager.py` - ConfigManager（设定管理）

管理应用程序设置。

环境变数（.env）读取设置
AGENT.md 从导入系统提示
以单字节模式缓存设置

设定项目：

GOOGLE_API_KEY: Gemini API 钥匙
GEMINI_MODEL：使用Gemini 模型（默认值： gemini-2.5-flash）
JGRANTS_MCP_URL: J格兰兹MCP 服务器URL

7. `mcp_agent/response_formatter.py` - ResponseFormatter（响应整形）

代理结果面向客户端JSON 整形。

出力形式：

{
  "answer": "ユーザー向けの最終回答（日本語）",
  "plan": [
    {
      "server": "jgrants",
      "tool": "search_subsidies",
      "arguments": {...},
      "reason": "..."
    }
  ],
  "toolResults": [
    {
      "server": "jgrants",
      "tool": "search_subsidies",
      "arguments": {...},
      "result": {...}
    }
  ],
  "_meta": {
    "agent": {
      "name": "mcp-client-backend-main-agent",
      "model": "gemini-2.5-flash"
    },
    "tools": {
      "used_count": 5
    }
  }
}

8. `mcp_agent/error_handler.py` - ErrorHandler（错误处理）

负责错误处理和日志输出。

机能：

按类型对异常进行分类（MCP连接错误、超时、内部错误等）
将堆栈跟踪输出到日志
向用户返回安全错误消息

📁 目录结构

mcp-client-backend/
├── server.py                 # FastAPI アプリケーション
├── mcp_agent/
│   ├── __init__.py
│   ├── agent.py              # エージェント本体（反復ループ実装）
│   ├── config_manager.py     # 設定管理
│   ├── connection_manager.py # MCP 接続管理
│   ├── task_manager.py       # 実行計画生成（前回結果を考慮）
│   ├── task_executor.py      # ツール実行
│   ├── error_handler.py      # エラーハンドリング
│   └── response_formatter.py # レスポンス整形
├── AGENT.md                  # システムプロンプト（Gemini 用）
├── pyproject.toml            # プロジェクト設定・依存関係
├── test_queries_individual.sh # テスト用curlコマンド集
├── .env                      # 環境変数（.gitignore に含まれる）
└── README.md                 # このファイル

🚀 安装，安装

所需环境

Python 3.11 以上
紫外线（包管理器）

安装说明

克隆存储库

git clone <repository-url>
cd mcp-client-backend

安装依赖关系

uv sync

设置环境变量 .env 创建文件并设置：

GOOGLE_API_KEY=your_google_api_key_here
GEMINI_MODEL=gemini-2.5-flash
JGRANTS_MCP_URL=https://your-jgrants-mcp-server-url

启动服务器

uv run fastapi dev server.py

服务器是 http://127.0.0.1:8000 中所述修改相应参数的值。

📝 API 使用例

健康检查

curl http://127.0.0.1:8000/healthz

工具列表检索

curl http://127.0.0.1:8000/tools

聊天（基本补贴搜索）

curl -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"東京都でテレワーク関連の補助金を探してください"}'

聊天（包括多个请求）

curl -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"まず、このjGrants MCPサーバーが正常に動作しているかどうかを確認し、その結果を簡潔に教えてください。そのうえで、東京都に所在する中小企業を対象とした、ITツール導入やDX推進を支援する補助金を検索してください。検索に成功した場合は、見つかった補助金の名称、最大補助額、申請期限、対象業種や従業員数などを整理して説明してください"}'

聊天（期望获取更多信息）

curl -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"東京都の中小企業向けITツール導入補助金を検索し、見つかった補助金の詳細（対象業種、申請要件、補助率など）を詳しく教えてください"}'

💡 系统特点及改进

重复执行循环

在以前的系统中，通过一次计划生成决定了全部的工具调用，但是在本系统中查看结果后再决定下一步中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。

优点：

如果搜索结果为0，则自动用其他关键字重新搜索
如果有搜索结果，则自动获取详细信息
更加灵活、适应性的动作

多关键字搜索

从用户的请求中提取多个相关关键字，分别单独搜索来修改标记元素的显示属性。

例：

要求：“DX推进”
搜索关键字：
- 「IT工具部署”
- 「DX推进」
- 「IT导入」
- 「DX」
- 数字化

通用提示设计

特定用例（例如：IT/DX相关），采用通用的提示设计。

特徴：

支持不同领域的补贴搜索
自动化关键字提取和搜索策略
正确判断参数的必要/任意

考虑上次结果的计划生成

在执行迭代时，考虑上次执行的结果，生成以下计划：。

例：

第1次：通过“IT工具导入”检索→0件
第2次：看上次的结果，用“系统”重新检索→3件
第3次：获取找到的补贴的详细信息

🔧 技术栈

Web 框架结构：FastAPI
LLM：谷歌Gemini API（Gemini-2.5闪存）
协议：MCP（模型上下文协议）
HTTP 客户机：httpx
设定管理：python dotenv
数据验证：Pydantic
包管理器：紫外线

🧪 测试

test_queries_individual.sh 准备了各种各样的测试用例。

# 個別のテストケースを実行
curl -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"東京都で農業や農林水産に関連する補助金を探してください"}'

🛠️ 开発

代码格式

Black 使用：

uv run black .

模具检查

Pylance（VS Code 扩张机能）を使用。.vscode/settings.json 中所述修改相应参数的值。

📚 相关资源

📄 许可证

（追加许可证信息）

使用说明

mcp客户端后端

📖 概要

主要特征

主要用途

🏗️ 系统体系结构

🔄 处理流程（详细信息）

1.请求接收

2.重复执行循环

3. 実行計画の生成（TaskManager）

4.工具执行器

5.最终回答生成

🧩 主要组件

1. server.py - FastAPI 应用程序

2. mcp_agent/agent.py - Agent（代理主机）

3. mcp_agent/task_manager.py - TaskManager（実行計画生成）

4. mcp_agent/task_executor.py - TaskExecutor（工具运行）

5. mcp_agent/connection_manager.py - ConnectionManager（MCP接続管理）

6. mcp_agent/config_manager.py - ConfigManager（设定管理）

7. mcp_agent/response_formatter.py - ResponseFormatter（响应整形）

8. mcp_agent/error_handler.py - ErrorHandler（错误处理）

📁 目录结构

🚀 安装，安装

所需环境

安装说明

📝 API 使用例

健康检查

工具列表检索

聊天（基本补贴搜索）

聊天（包括多个请求）

聊天（期望获取更多信息）

💡 系统特点及改进

重复执行循环

多关键字搜索

通用提示设计

考虑上次结果的计划生成

🔧 技术栈

🧪 测试

🛠️ 开発

代码格式

模具检查

📚 相关资源

📄 许可证

相关 MCP

Flomo笔记服务

网页抓取与搜索MCP服务器

用户名搜索MCP服务器

Jupyter笔记本MCP服务器

3D资产生成服务

文档搜索服务

1. `server.py` - FastAPI 应用程序

2. `mcp_agent/agent.py` - Agent（代理主机）

3. `mcp_agent/task_manager.py` - TaskManager（実行計画生成）

4. `mcp_agent/task_executor.py` - TaskExecutor（工具运行）

5. `mcp_agent/connection_manager.py` - ConnectionManager（MCP接続管理）

6. `mcp_agent/config_manager.py` - ConfigManager（设定管理）

7. `mcp_agent/response_formatter.py` - ResponseFormatter（响应整形）

8. `mcp_agent/error_handler.py` - ErrorHandler（错误处理）