使用说明

项目简介

本项目是一个基于 Model Context Protocol (MCP) 的服务器示例，旨在演示如何构建一个能够向LLM客户端提供结构化数据访问和工具调用的后端服务。该服务器利用 DuckDB 数据库作为数据源，并通过 Server-Sent Events (SSE) 协议与MCP客户端进行通信。此外，项目还包含一个将标准输入/输出 (stdio) 转换为 SSE 的网关，以便与 Claude 等客户端集成。

主要功能点

资源管理: 将 DuckDB 数据库中的表结构作为 MCP 资源进行托管和管理。客户端可以获取数据库表的 schema 信息。
工具注册与执行: 提供了 "query" 和 "visualise" 两个工具，允许客户端执行 SQL 查询并获取 DuckDB 数据库的查询结果。
Prompt 模板: (仓库中代码注释掉了 Prompt 相关功能，但 capabilities 中声明了 'templates: {}') 理论上支持 Prompt 模板的定义和渲染，虽然示例代码中未完全实现。
SSE 传输协议: 使用 SSE 作为 MCP 服务器与客户端之间的主要通信协议，实现实时的双向数据传输。
stdio 到 SSE 网关: 提供了一个网关组件，可以将基于 stdio 的 MCP 客户端请求转换为 SSE 协议，方便与特定的 LLM 客户端（如 Claude）集成。

安装步骤

克隆仓库

git clone https://github.com/boilingdata/mcp-server-and-gw.git
cd mcp-server-and-gw

安装依赖 确保已安装 Node.js 和 npm (或 yarn)。在项目根目录下运行：
```
npm install
```

服务器配置

MCP 客户端需要配置以下信息以连接到此 MCP 服务器。请注意，这里的配置是客户端需要的服务器连接信息，而不是服务器自身的配置。

{
  "serverName": "boiling-insights",
  "command": "node",
  "args": ["src/server.ts"]
}

配置参数说明:

'serverName': MCP 服务器的名称，这里设置为 "boiling-insights"。
'command': 启动 MCP 服务器的命令，这里使用 'node' 解释器。
'args': 传递给 'node' 命令的参数，指定服务器入口文件为 'src/server.ts'。

注意: 客户端还需要配置服务器的地址和端口，默认情况下，服务器运行在 'http://127.0.0.1:8808'。客户端通常需要配置 SSE 连接的 URL 为 'http://127.0.0.1:8808/sse'。

基本使用方法

启动 MCP 服务器 在项目根目录下，运行以下命令启动服务器：
```
npm run start-server
```
或者直接使用 Node.js 运行 'src/server.ts':
```
node src/server.ts
```
服务器启动后，会在终端输出 'Server is running on port 8808' 等信息。
运行 MCP 客户端 在另一个终端窗口中，运行示例 MCP 客户端 'src/client.ts'：
```
npm run start-client
```
或者直接使用 Node.js 运行 'src/client.ts':
```
node src/client.ts
```
客户端会连接到服务器，并发送请求列出资源、读取资源、列出工具和调用工具。客户端的输出会显示在终端上，例如列出的资源信息和工具调用结果。
使用 stdio 网关 (可选，针对 Claude 等客户端) 如果需要将此 MCP 服务器与基于 stdio 通信的 MCP 客户端（如 Claude）集成，可以使用 'src/claude_gateway.ts' 作为桥梁。首先确保服务器已启动。然后在新的终端窗口中，运行 gateway：
```
npm run start-gateway
```
或者直接使用 Node.js 运行 'src/claude_gateway.ts':
```
node src/claude_gateway.ts
```
启动 Claude 客户端，并配置其连接到 stdio 网关。gateway 会将 stdio 的请求转发到 SSE 服务器，并将 SSE 服务器的响应通过 stdio 返回给 Claude 客户端。

注意: 请确保 DuckDB 数据库文件 'test.duckdb' (如果服务器端使用了文件数据库) 存在或能够被正确创建。示例代码默认使用内存数据库，但 'src/server.ts' 中初始化 'const db = new Database("test.duckdb");' 看起来会尝试创建文件数据库。

关键词