Dolphin MCP

一个灵活的Python库和CLI工具，用于使用任何LLM模型与模型上下文协议（MCP）服务器进行交互。

概述

Dolphin MCP 既是 Python 库也是命令行工具，它允许您通过自然语言查询和与 MCP 服务器进行交互。它可以连接到任意数量的配置好的 MCP 服务器，将它们的工具提供给语言模型（OpenAI、Anthropic、Ollama、LMStudio），并提供一个对话式界面来访问和操作这些服务器中的数据。

该项目展示了如何：

同时连接到多个 MCP 服务器
列出并调用这些服务器提供的工具
使用函数调用功能与外部数据源进行交互
以用户友好的方式处理和呈现结果
创建一个具有清晰API的可重用 Python 库
在库之上构建命令行界面

功能

多提供商支持：支持 OpenAI、Anthropic、Ollama 和 LMStudio 模型
模块化架构：清晰的关注点分离，具有特定于提供商的模块
双重界面：可作为 Python 库或命令行工具使用
MCP 服务器集成：可同时连接到任意数量的 MCP 服务器
工具发现：自动发现和使用 MCP 服务器提供的工具
灵活的配置：通过 JSON 配置文件配置模型和服务器
环境变量支持：安全地存储 API 密钥在环境变量中
全面的文档：详细的用法示例和 API 文档
可安装的包：通过 pip 轻松安装，包含 dolphin-mcp-cli 命令

先决条件

在安装 Dolphin MCP 之前，请确保您已安装以下先决条件：

Python 3.10+
SQLite - 一个轻量级数据库，用于演示
uv/uvx - 一个快速 Python 包安装器和解析器

设置先决条件

Windows

Python 3.10+:
- 从 python.org 下载并安装
- 确保在安装过程中勾选“将 Python 添加到 PATH”
SQLite:
- 从 SQLite 网站下载预编译的二进制文件
- 选择“预编译的二进制文件 for Windows”部分，下载 sqlite-tools zip 文件
- 将文件解压到文件夹（例如 C:\sqlite）
- 将此文件夹添加到您的 PATH：
  - 打开控制面板 > 系统 > 高级系统设置 > 环境变量
  - 编辑 PATH 变量并添加您的 SQLite 文件夹路径
  - 通过在命令提示符中输入 sqlite3 --version 验证安装
uv/uvx:
- 以管理员身份打开 PowerShell 并运行：
```
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
- 重新启动您的终端并使用 uv --version 验证安装

macOS

Python 3.10+:
- 使用 Homebrew 安装：
```
brew install python
```
SQLite:
- SQLite 在 macOS 上预装，但您可以使用 Homebrew 更新：
```
brew install sqlite
```
- 使用 sqlite3 --version 验证安装
uv/uvx:
- 使用 Homebrew 安装：
```
brew install uv
```
- 或使用官方安装器：
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
- 使用 uv --version 验证安装

Linux (Ubuntu/Debian)

Python 3.10+:

sudo apt update
sudo apt install python3 python3-pip

SQLite:

sudo apt update
sudo apt install sqlite3

使用 sqlite3 --version 验证安装

uv/uvx:

curl -LsSf https://astral.sh/uv/install.sh | sh

使用 uv --version 验证安装

安装

选项 1：从 PyPI 安装（推荐）

pip install dolphin-mcp

这将安装库和 dolphin-mcp-cli 命令行工具。

选项 2：从源代码安装

克隆此仓库：

git clone https://github.com/cognitivecomputations/dolphin-mcp.git
cd dolphin-mcp

以开发模式安装包：
```
pip install -e .
```
通过复制示例文件并添加您的 OpenAI API 密钥来设置您的环境变量：
```
cp .env.example .env
```
然后编辑 .env 文件以添加您的 OpenAI API 密钥。
（可选）设置演示 dolphin 数据库：
```
python setup_db.py
```
这会创建一个包含 dolphin 信息的示例 SQLite 数据库，您可以使用它来测试系统。

配置

该项目使用两个主要的配置文件：

.env - 包含 OpenAI API 配置：

OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o
# OPENAI_BASE_URL=https://api.openai.com/v1  # 如果使用自定义基础 URL，取消注释并修改

mcp_config.json - 定义要连接的 MCP 服务器：

{
  "mcpServers": {
    "server1": {
      "command": "command-to-start-server",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR1": "value1",
        "ENV_VAR2": "value2"
      }
    },
    "server2": {
      "command": "another-server-command",
      "args": ["--option", "value"]
    }
  }
}

您可以添加任意数量的 MCP 服务器，客户端将连接到所有这些服务器并将它们的工具提供给语言模型。

使用

使用 CLI 命令

将您的查询作为参数运行 CLI 命令：

dolphin-mcp-cli "Your query here"

命令行选项

Usage: dolphin-mcp-cli [--model <name>] [--quiet] [--interactive | -i] [--config <file>] [--mcp-config <file>] [--log-messages <file>] [--debug] ['your question']

Options:
  --model <name>         指定要使用的模型（例如，gpt-4o, dolphin, qwen2.5-7b）
  --quiet                抑制中间输出（除错误外）
  --interactive, -i      启用交互式聊天模式。如果选择，第一个回合的 'your question' 参数是可选的。
  --config <file>        指定自定义 LLM 提供商配置文件（默认：config.yml）
  --mcp-config <file>    指定自定义 MCP 服务器配置文件（默认：examples/sqlite-mcp.json）
  --log-messages <file>  将所有 LLM 交互记录到 JSONL 文件
  --debug                启用调试日志（注意：`cli.py` 目前默认设置 DEBUG 级别）
  --help, -h             显示此帮助信息

交互式聊天模式

要启动 dolphin-mcp-cli 的交互模式，请使用 --interactive 或 -i 标志：

dolphin-mcp-cli --interactive
# 或
dolphin-mcp-cli -i

您也可以提供初始问题：

dolphin-mcp-cli -i "What dolphin species are endangered?"

在交互模式下，您可以与配置的模型进行持续对话。聊天将保持之前回合的上下文。输入 exit 或 quit 以结束会话。

以编程方式使用库

您也可以在 Python 代码中使用 Dolphin MCP 作为库：

import asyncio
from dolphin_mcp import run_interaction

async def main():
    result = await run_interaction(
        user_query="What dolphin species are endangered?",
        model_name="gpt-4o",  # 可选，未指定时将使用配置中的默认值
        config_path="mcp_config.json",  # 可选，默认为 mcp_config.json
        quiet_mode=False  # 可选，默认为 False
    )
    print(result)

# 运行异步函数
asyncio.run(main())

使用原始脚本（遗留）

您仍然可以直接运行原始脚本：

python dolphin_mcp.py "Your query here"

该工具将：

连接到所有配置的 MCP 服务器
列出每个服务器提供的可用工具
将您的查询和可用工具发送到选定的语言模型 API
执行模型请求的任何工具调用
以对话格式返回结果

示例查询

示例将取决于您配置的 MCP 服务器。使用演示 dolphin 数据库：

dolphin-mcp-cli --mcp-config examples/sqlite-mcp.json --model gpt-4o "What dolphin species are endangered?"

或使用您自己的自定义 MCP 服务器：

dolphin-mcp-cli "Query relevant to your configured servers"

您也可以指定要使用的模型：

dolphin-mcp-cli --model gpt-4o "What are the evolutionary relationships between dolphin species?"

要使用 LMStudio 提供商：

dolphin-mcp-cli --model qwen2.5-7b "What are the evolutionary relationships between dolphin species?"

为了更安静的输出（抑制中间结果）：

dolphin-mcp-cli --quiet "List all dolphin species in the Atlantic Ocean"

有关更多详细示例和使用案例，请参阅示例 README。

演示数据库

如果您运行 setup_db.py，它将创建一个包含关于 dolphin 物种的示例 SQLite 数据库。这作为演示系统如何与简单 MCP 服务器工作的示例提供。数据库包括：

各种 dolphin 物种的详细信息
物种之间的进化关系
保护状况和物理特征

这只是您可以使用 Dolphin MCP 客户端做的事情的一个示例。您可以将它连接到任何提供用于访问不同类型数据或服务的工具的 MCP 服务器。

要求

Python 3.10+
OpenAI API 密钥（或其他支持提供商的 API 密钥）

核心依赖项

openai
mcp[cli]
python-dotenv
anthropic
ollama
lmstudio
jsonschema

开发依赖项

pytest
pytest-asyncio
pytest-mock
uv

演示依赖项

mcp-server-sqlite

所有依赖项在您使用 pip 安装包时将自动安装。

工作原理

包结构

包组织成几个模块：

dolphin_mcp/ - 主包目录
- __init__.py - 包初始化和导出
- client.py - 核心 MCPClient 实现和 run_interaction 函数
- cli.py - 命令行界面
- utils.py - 用于配置和参数解析的实用函数
- providers/ - 特定于提供商的实现
  - openai.py - OpenAI API 集成
  - anthropic.py - Anthropic API 集成
  - ollama.py - Ollama API 集成
  - lmstudio.py - LMStudio SDK 集成

执行流程

CLI 解析命令行参数并调用库的 run_interaction 函数。
库从 mcp_config.json 加载配置并连接到每个配置的 MCP 服务器。
它从每个服务器检索可用工具的列表并格式化以供语言模型 API 使用。
将用户的查询连同可用工具一起发送到选定的语言模型（OpenAI、Anthropic、Ollama 或 LMStudio）。
如果模型决定调用工具，库将调用路由到相应的服务器并返回结果。
此过程持续进行，直到模型拥有它需要提供最终响应的所有信息。

这种模块化架构提供了极大的灵活性 - 您可以添加任何提供用于访问不同数据源或服务的工具的 MCP 服务器，客户端将自动将这些工具提供给语言模型。特定于提供商的模块也使得在将来添加对更多语言模型提供商的支持变得容易。

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

[在此处添加您的许可证信息]

QuixiAI/dolphin-mcp

星标增长

证据时间轴