test-dh-mcp

test-dh-mcp

本项目演示如何使用 FastMCP 实现来定义和运行 MCP（多通道协议）服务。项目包含工具注册、服务端/客户端使用，以及与 Claude Desktop 和 MCP Inspector 集成的示例。

• MCP 服务快速入门
• mcp Python 包文档（PyPI）

项目结构

• src/mcp_server.py — 运行 MCP 服务的主入口点（可配置为 SSE 或 stdio 传输）。
• src/dhmcp/__init__.py — 使用 @mcp_server.tool() 装饰器注册所有工具。
• src/mcp_client.py — 用于测试工具的异步客户端示例。
• requirements.txt — Python 依赖项（包括 mcp[cli] 和 autogen-ext）。

使用 uv 管理依赖项

uv 是一款现代、超高速的 Python 包管理器和运行器。它可以作为 pip 和 venv 的直接替代工具，提供更快的安装速度和更完善的依赖项管理。

核心概念

• pyproject.toml：指定项目依赖项和元数据的现代推荐方式。uv 会将其作为真实数据源。
• requirements.txt：支持与传统 Python 工具和工作流兼容。如果使用 pyproject.toml，则可以不使用此文件。
• uv.lock：用于确保安装可复现的锁定文件（由 uv 自动管理）。

现代工作流（推荐）

1. 直接向项目添加依赖项：

   uv pip install <package>
   # Example:
   uv pip install autogen-ext mcp[cli]
   

   这会更新 pyproject.toml 和 uv.lock。
2. 同步环境：

   uv pip install  # Installs all dependencies from pyproject.toml
   

3. 运行脚本：

   uv run src/mcp_server.py
   uv run src/mcp_client.py
   

4. 升级依赖项：

   uv sync --upgrade
   

兼容性工作流（requirements.txt）

• 如果已有 requirements.txt，可以使用：

  uv pip install -r requirements.txt
  # or
  uv add --requirements requirements.txt
  

• 这会同步依赖项并更新锁定文件。你可以让这两个文件保持同步，以获得最大兼容性。

注意事项

• 使用 uv 时，requirements.txt 并非必需。对于新项目，你可以完全依赖 pyproject.toml 和 uv.lock。
• 对于旧项目或需要与 pip 用户共享的项目，请保持 requirements.txt 更新。
• uv 可在有或没有虚拟环境的情况下使用。如果需要创建虚拟环境，可使用 uv venv .venv。
• 如果有多个环境，请使用 --active 指定当前激活的环境。

快速入门：服务端

1. 安装依赖项

建议使用虚拟环境：

• 使用 venv：

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

• 使用 uv：

uv pip install -r requirements.txt

2. 运行 MCP 服务

在项目根目录中运行（选择适合你使用场景的传输方式）：

• SSE 传输（默认，适用于浏览器/网页客户端）：

  python src/mcp_server.py
  # or, explicitly:
  python src/mcp_server.py --transport sse
  # or, using uv:
  uv run src/mcp_server.py
  

  服务将在 http://localhost:8000/sse 上监听

• Stdio 传输（推荐用于 Claude Desktop/Inspector）：

  python src/mcp_server.py --transport stdio
  # or, using uv:
  uv run src/mcp_server.py --transport stdio
  

  服务将通过 stdio 通信（无需 HTTP 端口）。

你应该会看到日志输出，表明服务正通过所选传输方式运行。

快速入门：客户端

注意： Python 客户端（mcp_client.py）要求 MCP 服务以 SSE 模式（默认）运行。如果服务以 stdio 模式运行，则无法使用。

1. 安装依赖项

建议使用虚拟环境：

• 使用 venv：

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

• 使用 uv：

uv pip install -r requirements.txt

2. 运行 MCP 客户端

在项目根目录中运行：

• 使用 venv：

cd src
python -m mcp_client

• 使用 uv：

cd src
uv run mcp_client.py

你应该会看到日志输出，表明客户端正在运行并列出可用工具。

Claude Desktop

你可以将 Claude Desktop 连接到本地 stdio MCP 服务，以使用自定义工具。

1. 编辑 ~/Library/Application\ Support/Claude/claude_desktop_config.json，添加你的 MCP 服务。Deephaven 工作进程配置现在完全通过 JSON 配置文件处理，并且必须使用必需的 DH_MCP_CONFIG_FILE 环境变量指定文件路径。没有默认路径——必须始终设置此环境变量。

   Claude Desktop 配置示例（使用 venv）：

   {
     "mcpServers": {
       "test-dh-mcp": {
         "command": "/Users/chip/dev/test-dh-mcp/.venv/bin/python3",
         "args": ["/Users/chip/dev/test-dh-mcp/src/mcp_server.py", "--transport", "stdio"],
         "env": {
           "DH_MCP_CONFIG_FILE": "/Users/chip/dev/test-dh-mcp/deephaven_workers.json"
         }
       }
     }
   }
   

   或使用 uv：

   {
     "mcpServers": {
       "test-dh-mcp": {
         "command": "uv",
         "args": [
           "--directory",
           "/Users/chip/dev/test-dh-mcp/src",
           "run",
           "mcp_server.py",
           "--transport",
           "stdio"
         ],
         "env": {
           "DH_MCP_CONFIG_FILE": "/Users/chip/dev/test-dh-mcp/deephaven_workers.json"
         }
       }
     }
   }
   

   注意：如果你的配置文件在项目根目录下的名称不是 deephaven_workers.json，或者你希望明确指定配置文件位置，请始终在 env 部分设置 DH_MCP_CONFIG_FILE。

      "args": [
        "--directory",
        "/Users/chip/dev/test-dh-mcp/src",
        "run", 
        "mcp_server.py", 
        "--transport", 
        "stdio"
      ],
      "env": {
        "DH_MCP_SERVER_NAME": "test-dh-mcp",
        "DH_MCP_HOST": "localhost",
        "DH_MCP_PORT": "10000",
        "DH_MCP_AUTH_TYPE": "Anonymous"
      }
    }
   

   } }

注意： Deephaven 会话配置部分中列出的所有 DH_MCP_* 环境变量都可以在此处设置。这些变量控制每次工具调用所使用的 Deephaven 会话。

4. 重启 Claude Desktop。
5. 调试日志可在 ~/Library/Logs/Claude/ 中找到

Deephaven Worker 配置

现在，所有 Deephaven worker 配置均通过 JSON 文件处理。必须使用 DH_MCP_CONFIG_FILE 环境变量指定此文件的路径。没有默认路径——此变量为必填项。

配置文件应如下所示：

{
  "workers": {
    "worker1": {
      "host": "localhost",
      "port": 10000,
      "auth_type": "Anonymous",
      "auth_token": "",
      "never_timeout": true
    },
    "worker2": {
      "host": "otherhost",
      "port": 10001,
      "auth_type": "Bearer",
      "auth_token": "YOUR_TOKEN"
    }
  },
  "default_worker": "worker1"
}

• workers 对象将 worker 名称映射到其连接设置。
• default_worker 为可选项，在工具调用未指定 worker 名称时使用。如果设置了该项，其值必须与 workers 字典中的某个键匹配。

重要： DH_MCP_CONFIG_FILE 环境变量必须始终设置为 worker 配置文件的路径。没有默认配置路径。

每个 worker 支持的字段：

字段	类型	描述
host	str	Deephaven 服务主机名或 IP（可选）
port	int	Deephaven 服务端口（可选）
auth_type	str	身份验证类型（例如，Anonymous、Bearer）（可选）
auth_token	str	身份验证令牌（可选）
never_timeout	bool	会话是否永不超时（可选，默认值：True）
session_type	str	会话类型，例如 python（可选，默认值：'python'）
use_tls	bool	是否使用 TLS/SSL（可选，默认值：False）
tls_root_certs	str 或 null	TLS 根证书的路径（可选）
client_cert_chain	str 或 null	客户端证书链的路径（可选）
client_private_key	str 或 null	客户端私钥的路径（可选）

注意：根据使用场景和身份验证方式，可以只为 worker 定义上述字段中的一部分。没有字段是严格必填的；在可能的情况下会使用默认值。

工具用法

• echo_tool(message: str) -> str：返回输入消息，并在前面加上 'Echo:'。
• gnome_count_colorado() -> int：返回科罗拉多州当前的地精数量（演示工具）。
• deephaven_worker_names() -> list[str]：返回配置文件中配置的所有 Deephaven worker 名称。
• deephaven_default_worker() -> str：返回配置中设置的默认 worker 名称（如果未设置，则返回 None）。
• deephaven_list_tables(worker_name: str = None) -> list：列出指定 worker 的表名称。如果未提供 worker_name，则使用配置中的 default_worker。
• deephaven_table_schemas(worker_name: str = None) -> list：返回指定 worker 中所有表的架构。如果未提供 worker_name，则使用配置中的 default_worker。

如何设置多个 worker，请参阅上方的示例配置文件。

注册工具

使用 @mcp_server.tool() 装饰器，在 dhmcp/__init__.py 中定义新工具。示例：

@mcp_server.tool()
def echo_tool(message: str) -> str:
    """
    Echo tool that returns the input message prefixed with 'Echo:'.
    """
    return f"Echo: {message}"

故障排除

• 确保从正确的目录运行命令（直接执行脚本时使用 src）。
• 如果更改了工具定义，请重启服务。
• 如果遇到连接问题，请检查服务是否正在运行并监听预期地址/端口（用于 SSE），或者是否已通过 stdio 正确连接（用于 Claude/Inspector）。

服务是否正在运行？

• SSE 模式：

  curl http://localhost:8000/sse
  

• Stdio 模式：
  • 检查 Claude/Inspector 日志，确认连接成功并已列出工具。

MCP Inspector

MCP Inspector 是一款可用于检查 MCP 服务状态的工具。

1. 安装 MCP Inspector：

   npm install -g @modelcontextprotocol/inspector@latest
   

2. 运行 MCP Inspector：

⚠️ WARNING: 使用 MCP Inspector 时，所有字符串值都必须加引号输入（例如 "worker1"）。 如果不加引号，Inspector 可能会向服务发送 null 或无效值。 可以点击 Format JSON 按钮来验证该值。

- ** SSE 模式： **

    - 使用 `venv`：

    ```bash
    cd /Users/chip/dev/test-dh-mcp/src
    npx @modelcontextprotocol/inspector@latest \
    /Users/chip/dev/test-dh-mcp/venv/bin/python3 mcp_server.py --transport sse
    ```

    - 使用 `uv`：

    ```bash
    cd /Users/chip/dev/test-dh-mcp/src
    npx @modelcontextprotocol/inspector@latest \
    uv run mcp_server.py --transport sse
    ```

- ** Stdio 模式： **

    - 使用 `venv`：

    ```
    cd /Users/chip/dev/test-dh-mcp/src
    npx @modelcontextprotocol/inspector@latest \
    /Users/chip/dev/test-dh-mcp/venv/bin/python3 mcp_server.py --transport stdio
    ```

    - 使用 `uv`：

    ```bash
    cd /Users/chip/dev/test-dh-mcp/src
    npx @modelcontextprotocol/inspector@latest \
    uv run mcp_server.py --transport stdio
    ```