使用说明

项目简介

本项目 'mcp-server' 是一个实现了 Model Context Protocol (MCP) 的服务端，旨在演示如何构建一个能够为大语言模型 (LLM) 提供外部工具和上下文信息的后端服务。通过 MCP 协议，LLM 客户端可以连接到此服务器，调用预先注册的工具来扩展自身能力，例如查询天气信息或获取 GitHub 用户信息。

主要功能点

工具注册与执行: 服务端可以注册多种工具（如本示例中的天气查询和 GitHub 用户信息查询工具），并接收客户端请求执行这些工具，返回结构化结果。
标准 MCP 协议通信: 使用 '@modelcontextprotocol/sdk' 库实现，遵循 MCP 协议规范与客户端进行通信。
Stdio 传输协议: 使用标准输入输出 (stdio) 作为默认的传输协议，方便部署和集成。
示例工具: 内置了天气预报查询工具（使用高德地图API）和 GitHub 用户信息查询工具（使用 GitHub API），展示了如何集成外部 API 到 MCP 服务器中。
白盒过程可视化 (客户端功能): 配套的客户端项目 ('mcp-client-typescript') 提供了 Web API 和 SSE 接口，支持将工具调用过程可视化，方便用户理解 LLM 的推理和工具调用过程。

安装步骤

安装 Node.js 环境: 确保你的机器上已安装 Node.js 和 npm (或 yarn)。

克隆仓库: 将 'mcp-server' 仓库克隆到本地。

git clone https://github.com/chenshuai2144/mcp-server.git
cd mcp-server

安装依赖: 在项目根目录下运行 'npm install' 或 'yarn install' 安装项目依赖。
```
npm install
```
配置环境变量: 复制 '.env.example' 文件并重命名为 '.env'，根据需要配置以下环境变量：
- 'LLM_API_KEY': (客户端使用) 大语言模型 API 密钥 (例如 Deepseek API Key)。
- 'GAODE_KEY': 高德地图 API 密钥，用于天气查询工具。你需要在高德地图开放平台申请 Web 服务 API 密钥。

服务器配置

MCP 服务器是设计为通过标准输入输出 (stdio) 与 MCP 客户端通信的。因此，MCP 客户端需要配置启动 MCP 服务器的命令和参数。

MCP 客户端配置示例 (JSON 格式):

{
  "serverName": "mcp-server-weather",
  "command": "node",
  "args": [
    "/path/to/mcp-server/dist/src/index.js"  // 请替换为实际的 mcp-server 服务端入口文件路径
  ]
}

参数说明:

'serverName': MCP 服务器的名称，用于客户端识别。
'command': 启动 MCP 服务器的命令，这里使用 'node' 运行 JavaScript 文件。
'args': 传递给启动命令的参数数组。
- '"/path/to/mcp-server/dist/src/index.js"': 需要替换为实际的 'mcp-server' 服务端入口文件 'index.js' 的绝对路径。 请根据你的项目克隆位置进行调整。

注意: MCP 客户端需要能够执行 'node' 命令，并访问到 'mcp-server' 服务端入口文件。

基本使用方法

启动 MCP 服务器: 在 'mcp-server' 项目根目录下，运行以下命令启动服务端：
```
npm run start
```
或者
```
node dist/src/index.js
```
服务端成功启动后，会在控制台输出 'Weather MCP Server running on stdio'。
启动 MCP 客户端: 在 'mcp-client-typescript' 目录下，按照客户端 README.md 的说明启动客户端，并连接到刚刚启动的 MCP 服务器。例如，假设服务端入口文件路径为 '/path/to/mcp-server/dist/src/index.js'，则客户端启动命令可能为：
```
node dist/mcp-client-typescript/src/index.js /path/to/mcp-server/dist/src/index.js
```
通过客户端与 LLM 交互: 客户端启动后，你可以通过客户端的命令行界面或 Web API (http://localhost:3000/sse) 与 LLM 进行交互。例如，在命令行中输入查询：'北京今天的天气怎么样？'，客户端会将查询发送给 LLM，并根据 LLM 的指示调用 MCP 服务器提供的工具获取天气信息，最终返回结果。

Web API 使用示例 (POST /sse):

curl -X POST \
  http://localhost:3000/sse \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "北京今天的天气怎么样？"
  }'

关键词