海豚-MCP

Name: 海豚-MCP
Author: QuixiAI

作者：QuixiAI525 星标更新：2025-05-21

安装使用来源：spider==github.com

项目介绍

Dolphin MCP

一个灵活的Python库和CLI工具，用于通过任何LLM模型与Model Context Protocol (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网站下载预编译的二进制文件
- 选择“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：
- macOS上已预装SQLite，但可以使用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密钥。
（可选）设置演示海豚数据库：
```
python setup_db.py
```
这会创建一个带有海豚信息的样本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 "您的查询在这里"

命令行选项

用法：dolphin-mcp-cli [--model <name>] [--quiet] [--interactive | -i] [--config <file>] [--mcp-config <file>] [--log-messages <file>] [--debug] ['您的问题']

选项：
  --model <name>         指定要使用的模型（例如，gpt--4o, dolphin, qwen2.5-7b）
  --quiet                抑制中间输出（除了错误）
  --interactive, -i      启用交互式聊天模式。如果选择，则'您的问题'参数对于第一轮是可选的。
  --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 "哪些海豚物种濒临灭绝？"

在交互模式下，您可以与配置的模型进行连续对话。聊天将维护来自先前回合的上下文。键入exit或quit以结束会话。

作为库编程使用

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

import asyncio
from dolphin_mcp import run_interaction

async def main():
    result = await run_interaction(
        user_query="哪些海豚物种濒临灭绝？",
        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 "您的查询在这里"

该工具将：

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

示例查询

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

dolphin-mcp-cli --mcp-config examples/sqlite-mcp.json --model gpt-4o "哪些海豚物种濒临灭绝？"

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

dolphin-mcp-cli "与您配置的服务器相关的查询"

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

dolphin-mcp-cli --model gpt-4o "海豚物种之间的进化关系是什么？"

要使用LMStudio提供商：

dolphin-mcp-cli --model qwen2.5-7b "海豚物种之间的进化关系是什么？"

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

dolphin-mcp-cli --quiet "列出大西洋中的所有海豚物种"

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

演示数据库

如果您运行setup_db.py，它将创建一个带有海豚物种信息的样本SQLite数据库。这是展示系统如何与简单的MCP服务器一起工作的示例。数据库包括：

关于各种海豚物种的信息
物种之间的进化关系
保护状态和物理特征

这只是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。

许可证

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