使用说明

项目简介

Tiny-OAI-MCP-Agent 是一个演示项目，旨在展示大型语言模型 (LLM) 如何通过模型上下文协议 (MCP) 与外部工具进行交互。它基于 OpenAI 兼容的 LLM，并使用 MCP 协议连接到一个 SQLite 数据库服务器。用户可以通过自然语言提示，让 LLM 调用数据库工具来查询和操作 SQLite 数据库。

主要功能点

自然语言数据库操作: 用户可以使用自然语言指令，例如 "show tables" 或 "create table students"，来查询和操作 SQLite 数据库。
MCP协议集成: 项目实现了 MCP 客户端，可以与 MCP 服务器进行通信，获取工具列表并调用工具。
工具注册与调用: MCP 客户端从 MCP 服务器获取数据库工具 (如 'execute_query', 'get_table_metadata', 'list_tables')，并将这些工具注册到 LLM 的 Function Calling 功能中。LLM 可以根据用户提示自主选择并调用合适的工具。
OpenAI 兼容性: 项目使用 OpenAI 的 Python 客户端库 'openai'，可以与任何 OpenAI API 兼容的 LLM 服务提供商（如 OpenRouter, Fireworks.ai）配合使用，只要这些服务提供商的模型支持 Function Calling。
Dockerized MCP 服务器: 项目默认配置使用 Docker 容器运行 SQLite MCP 服务器，简化了服务器的部署和管理。

安装步骤

克隆仓库:

git clone https://github.com/jalr4ever/Tiny-OAI-MCP-Agent.git
cd Tiny-OAI-MCP-Agent

创建并激活 conda 环境 (可选，推荐):

conda create -n tiny-oai-mcp-agent python=3.11
conda activate tiny-oai-mcp-agent

安装 Python 依赖:

pip install -r requirements.txt

配置环境变量:

复制 '.env.template' 文件并重命名为 '.env'。

根据你的 OpenAI 兼容服务提供商的信息，修改 '.env' 文件中的 'OPENAI_API_KEY', 'OPENAI_API_BASE', 和 'LLM_MODEL'。

例如，使用 OpenRouter + qwen-turbo:

OPENAI_API_KEY='sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
OPENAI_API_BASE='https://openrouter.ai/api/v1'
LLM_MODEL='qwen/qwen-turbo'

请参考 README.md 中 "Setup & Executing" -> ".env" 部分的示例，选择适合你的服务提供商和模型配置。

服务器配置

Tiny-OAI-MCP-Agent 客户端需要配置连接 MCP 服务器的参数。该项目使用 Stdio 传输协议连接到在 Docker 容器中运行的 SQLite MCP 服务器。

配置信息 (JSON 格式):

{
  "server name": "sqlite-mcp-server",
  "command": "docker",
  "args": [
    "run",
    "--rm",
    "-i",
    "-v",
    "mcp-test:/mcp",
    "mcp/sqlite",
    "--db-path",
    "/mcp/test.db"
  ],
  "description": "使用 Docker 运行 SQLite MCP 服务器。 \n- '--rm': 容器退出后自动删除。\n- '-i':  以交互模式运行。\n- '-v mcp-test:/mcp':  将本地命名卷 'mcp-test' 挂载到容器内的 '/mcp' 目录，用于持久化数据库文件。\n- 'mcp/sqlite':  使用的 Docker 镜像为 'mcp/sqlite'，这是一个预构建的包含 SQLite MCP 服务器的镜像。\n- '--db-path /mcp/test.db':  指定容器内数据库文件的路径为 '/mcp/test.db'。"
}

注意: 以上 JSON 配置信息描述了 MCP 客户端 如何启动和连接 MCP 服务器。用户 无需手动配置 MCP 服务器，因为 'agent.py' 脚本会自动使用 Docker 启动服务器。用户需要配置的是 OpenAI 兼容的 LLM 服务提供商信息 (在 '.env' 文件中)。

基本使用方法

运行 MCP 客户端 ('agent.py'):
```
python agent.py
```
在终端中输入自然语言提示:
- 客户端启动后，会显示提示 "Enter your prompt (or 'quit' to exit): "。
- 输入你的自然语言指令，例如:
  - 'show tables' (显示数据库中的表)
  - 'create table students with 4 columuns for me, decide column detail by yourself' (创建一个包含 4 列的 students 表)
  - 'show metadata from users' (显示 users 表的元数据)
  - 'quit' (退出程序)
查看 LLM 的响应:
- 客户端会调用 LLM 处理你的提示，并根据需要调用 MCP 服务器提供的数据库工具。
- LLM 的响应会显示在终端中。

示例:

Enter your prompt (or 'quit' to exit): show tables

Response: Here are the tables available in the database:

1. **users**
2. **stock**
3. **students**

If you need more information about either of these tables or want to perform operations on them, just let me know!

Enter your prompt (or 'quit' to exit): quit

关键词