adk MCP server db

ADK代理MCP服务器

此项目演示了一个与本地SQLite数据库交互的Agent Development Kit（ADK）代理。模型上下文协议（MCP）服务器为交互提供了便利，该服务器公开了查询和修改数据库的工具。

项目结构

adk-mcp/
├── local_mcp/
│   ├── agent.py             # The ADK agent for the local SQLite DB
│   ├── server.py            # The MCP server exposing database tools
│   ├── create_db.py         # Script to initialize the SQLite database
│   ├── database.db          # The SQLite database file
│   └── __init__.py
├── remote_mcp_agent/        # Example agent for connecting to a remote MCP server
│   ├── agent.py             # The ADK agent configured for a remote MCP
│   └── __init__.py
├── .env                   # For GOOGLE_API_KEY (ensure it's in .gitignore if repo is public)
├── requirements.txt       # Python dependencies
└── readme.md              # This file

安装说明

1.先决条件

• Python 3.8或更高版本
• 访问终端或命令提示符

2.创建和激活虚拟环境

强烈建议使用虚拟环境来管理项目依赖关系。

# Create a virtual environment (e.g., named .venv)
python3 -m venv .venv

激活虚拟环境：

在macOS/Linux上：

# Activate virtual environment
source .venv/bin/activate

在Windows上：

# Activate virtual environment
.venv\Scripts\activate

3.安装依赖项

使用pip安装所有必需的Python包：

# Install all dependencies from requirements.txt
pip install -r requirements.txt

4.设置Gemini API密钥（用于ADK代理）

此项目中的ADK代理使用Gemini模型。您需要一个Gemini API密钥。

1. 创建或使用现有 谷歌人工智能工作室 账户

1. 从获取Gemini API密钥 API密钥部分.

1. 将API键设置为环境变量。创建一个 .env 文件在 根 adk-mcp 项目 （即，旁边 local_mcp 文件夹和 readme.md):

   # .env
   GOOGLE_API_KEY=your_gemini_api_key_here

这 server.py 和 agent.py 将加载此密钥。

5.创建SQLite数据库和表

该项目包括一个创建和填充SQLite数据库的脚本(database.db)有一些初始表格(users, todos)以及虚拟数据。

导航到 local_mcp 目录并运行脚本：

cd local_mcp
python3 create_db.py
cd ..

这将创建 local_mcp/database.db 如果它还不存在。

运行代理和MCP服务器

ADK代理商(local_mcp/agent.py)配置为自动启动MCP服务器(local_mcp/server.py)当它初始化其MCP工具集时。

要运行代理，请执行以下操作：

1. 确保您的虚拟环境处于活动状态，并且您位于 adk-mcp 项目。

1. 执行代理脚本：

   python3 local_mcp/agent.py

这将：

• 启动 agent.py 脚本。
• 代理在初始化时 MCPToolset，将执行 python3 local_mcp/server.py 命令。
• 这 server.py （MCP服务器）将启动并通过stdio监听来自代理的工具调用。
• 然后，代理将准备好处理您的指令（您通常会在使用此代理的客户端应用程序或测试环境中提供这些指令）。

您应该看到代理（如果有的话）和MCP服务器（在 local_mcp/mcp_server_activity.log，如果您在中取消注释流处理程序，则可能会发送到控制台 server.py).

其他MCP服务器的附加设置（Node.js和Docker）

而本地SQLite MCP服务器在这个特定项目中(local_mcp/server.py)只需要Python来执行，您可能希望使用此ADK代理连接到 *其他* 具有不同运行时依赖关系的MCP服务器。此类外部MCP服务器的两个常见依赖项是Node.js（它提供 npx 用于运行基于JavaScript的服务器）和Docker（用于作为Docker镜像分发的服务器）。

如果您计划使用需要这些的MCP服务器，以下是如何设置它们：

Node.js和npx

npx 是随附的包运行器工具 npm （节点包管理器），它包含在Node.js中。它通常用于运行使用Node.js构建的MCP服务器，而无需全局安装。

• 安装：下载并安装Node.js（包括 npm 和 npx)从 建议安装LTS（长期支持）版本。
• 验证：安装后，打开一个新的终端或命令提示符窗口，通过键入以下内容来验证安装：

  node -v
  npm -v
  npx -v

您应该看到为每个命令打印的版本号，确认它们已安装并位于系统的PATH中。

码头工人

Docker允许应用程序在称为容器的隔离环境中打包和运行。一些MCP服务器作为Docker镜像分发，使其易于在不同的操作系统上运行。

• 安装：从下载并安装Docker桌面 Docker Desktop可用于Windows、macOS和Linux，并提供图形界面和命令行工具。
• 安装后：确保Docker Desktop在安装后运行，因为这会启动Docker守护进程（管理容器的后台服务）。
• 验证：打开终端或命令提示符，键入以下命令验证Docker安装：

  docker --version
  # You can also run a test container to ensure Docker is working correctly:
  # docker run hello-world

第一个命令应该显示您的Docker版本。跑步 docker run hello-world 将下载并运行一个小型测试映像，确认Docker可以运行。

设置这些工具将扩大ADK代理可能与之交互的MCP服务器的范围。

可用数据库工具（由MCP服务器公开）

这 local_mcp/server.py 公开以下工具供ADK代理使用：

• list_db_tables(dummy_param: str) -> dict：列出数据库中的所有表。

- *备注*：需要a dummy_param 由于当前ADK模式生成行为导致的字符串；代理的指令指导它提供默认值。

• get_table_schema(table_name: str) -> dict：检索指定表的架构（列名和类型）。
• query_db_table(table_name: str, columns: str, condition: str) -> list[dict]：查询表。

- columns：逗号分隔的列列表（例如，“id，用户名”）或“\*”表示所有列。 - condition：SQL WHERE子句（例如，“email LIKE'%@example.com'”）。如果没有隐含条件，则指示代理使用“1=1”。

• insert_data(table_name: str, data: dict) -> dict：在表中插入新行。

- data：一个字典，其中键是列名，值是新行的相应数据。

• delete_data(table_name: str, condition: str) -> dict：根据条件从表中删除行。

- *备注*：作为安全措施，条件不能为空。

代理人(local_mcp/agent.py)有关于如何有效使用这些工具的具体说明，包括如果最终用户的请求没有明确提供，则对参数使用智能默认值。

故障排除

• No such file or directory 为了 server.py:

- 确保 PATH_TO_YOUR_MCP_SERVER_SCRIPT 在……里面 local_mcp/agent.py 正确指向 local_mcp/server.py。当前设置使用 (Path(__file__).parent / "server.py").resolve()，文件夹合并后应该是正确的。

• McpError: Input must be an instance of Schema, got （客户端错误）:

- 如果发生以下情况，则可能会出现此错误 adk_to_mcp_tool_type 在……里面 server.py 生成a None 工具的输入模式。这 list_db_tables 工具在 server.py 包括a dummy_param 作为无参数函数解决此已知问题的一种方法。服务器还有一个补丁，可以提供默认模式（如果有的话） None.

• 数据库错误（例如，“没有这样的表”）:

- 确保你已经跑步了 python3 local_mcp/create_db.py 创建 database.db 文件及其表格。 - 验证 DATABASE_PATH 在……里面 local_mcp/server.py 正确指向 local_mcp/database.db.

• API关键问题:

- 确保你的 GOOGLE_API_KEY 在中正确设置 .env 项目根目录中的文件，并且正在加载该文件。

• MCP服务器日志:

- 检查 local_mcp/mcp_server_activity.log 获取MCP服务器的详细日志，这可以帮助诊断工具调用或数据库操作的问题。

未来增强功能（想法）

• 向MCP服务器添加“update_data”工具。
• 在服务器工具中实现更复杂的错误处理和报告。
• 开发一个简单的客户端应用程序（例如CLI或基本web UI）来与ADK代理交互。