# Mcp+Nodejs_streamable_http

**Repository Path**: 6feel/mcp--nodejsstreamablehttp

## Basic Information

- **Project Name**: Mcp+Nodejs_streamable_http
- **Description**: streamable-http 实现的mcp服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-02
- **Last Updated**: 2025-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WJB HTTP MCP Server

基于 TypeScript SDK 的 HTTP MCP (Model Context Protocol) 服务器实现。

## 功能特性

- ✅ 使用 StreamableHTTP 传输协议
- ✅ 支持会话管理
- ✅ 内置计算器和回声工具
- ✅ 提供系统信息和时间资源
- ✅ 健康检查端点
- ✅ 优雅关闭处理

## 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 构建项目

```bash
npm run build
```

### 3. 启动服务器

```bash
# 生产模式
npm start

# 开发模式（构建并启动）
npm run dev
```

服务器将在 `http://localhost:3000` 启动。

### 4. 自定义端口

```bash
# 使用环境变量指定端口
PORT=8080 npm start
```

## API 端点

| 端点 | 方法 | 描述 |
|------|------|------|
| `/mcp` | POST | MCP 客户端到服务器通信 |
| `/mcp` | GET | 服务器发送事件 (SSE) |
| `/mcp` | DELETE | 终止 MCP 会话 |
| `/health` | GET | 健康检查 |
| `/` | GET | 服务器信息 |

## 可用工具

### 1. Calculator (计算器)

执行基本数学运算。

**参数：**
- `operation`: "add" | "subtract" | "multiply" | "divide"
- `a`: number - 第一个数字
- `b`: number - 第二个数字

**示例：**
```json
{
  "operation": "add",
  "a": 10,
  "b": 5
}
```

### 2. Echo (回声)

回显输入的文本。

**参数：**
- `text`: string - 要回显的文本

**示例：**
```json
{
  "text": "Hello, MCP!"
}
```

## 可用资源

### 1. System Information

**URI:** `system://info`

提供基本的系统信息，包括平台、架构、Node.js 版本等。

### 2. Current Time

**URI:** `time://current`

提供当前的日期和时间信息。

## 验证服务器运行

### 方法 1: 健康检查

```bash
curl http://localhost:3000/health
```

预期响应：
```json
{
  "status": "healthy",
  "timestamp": "2024-01-20T10:30:00.000Z",
  "activeSessions": 0
}
```

### 方法 2: 服务器信息

```bash
curl http://localhost:3000/
```

### 方法 3: 使用内置测试客户端

```bash
# 构建项目
npm run build

# 运行测试客户端
node build/test-client.js
```

测试客户端将执行以下操作：
1. 初始化 MCP 连接
2. 列出可用工具
3. 列出可用资源
4. 测试计算器工具
5. 测试回声工具
6. 读取系统信息资源
7. 读取时间资源

### 方法 4: 使用 MCP Inspector

```bash
npx @modelcontextprotocol/inspector
```

然后在浏览器中访问 `http://localhost:5173`，配置连接到 `http://localhost:3000/mcp`。

### 方法 5: 手动 MCP 请求

#### 初始化连接

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {
        "tools": {},
        "resources": {}
      },
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'
```

#### 列出工具（需要会话ID）

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/list",
    "params": {}
  }'
```

## 客户端配置

### Claude Desktop 配置

将以下配置添加到 Claude Desktop 的配置文件中：

```json
{
  "mcpServers": {
    "wjb-http-mcp-server": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

**注意：** 截至目前，Claude Desktop 可能还不完全支持 StreamableHTTP 协议。请查看最新的 Claude Desktop 文档。

### 其他 MCP 客户端

使用 `mcp-config.json` 文件中的配置，或参考您的 MCP 客户端文档。

## 开发

### 项目结构

```
wjb-mcp-server-http/
├── src/
│   ├── server.ts          # 主服务器代码
│   └── test-client.ts     # 测试客户端
├── build/                 # 编译输出目录
├── package.json           # 项目配置
├── tsconfig.json          # TypeScript 配置
├── mcp-config.json        # MCP 客户端配置示例
└── README.md              # 项目文档
```

### 可用脚本

- `npm run build` - 编译 TypeScript 代码
- `npm start` - 启动生产服务器
- `npm run dev` - 开发模式（构建并启动）
- `npm run watch` - 监听文件变化并重新编译

### 添加新工具

在 `src/server.ts` 中的 `createMcpServer()` 函数里添加新的工具：

```typescript
server.registerTool(
  "your-tool-name",
  {
    title: "Your Tool Title",
    description: "Tool description",
    inputSchema: {
      // 使用 Zod 定义参数模式
      param1: z.string().describe("Parameter description"),
    },
  },
  async ({ param1 }) => {
    // 工具逻辑
    return {
      content: [
        {
          type: "text",
          text: `Result: ${param1}`,
        },
      ],
    };
  }
);
```

### 添加新资源

```typescript
server.registerResource(
  "resource-name",
  "scheme://path",
  {
    title: "Resource Title",
    description: "Resource description",
    mimeType: "text/plain",
  },
  async (uri) => {
    return {
      contents: [
        {
          uri: uri.href,
          text: "Resource content",
        },
      ],
    };
  }
);
```

## 故障排除

### 常见问题

1. **端口已被占用**
   ```
   Error: listen EADDRINUSE: address already in use :::3000
   ```
   解决方案：使用不同的端口 `PORT=8080 npm start`

2. **依赖安装失败**
   确保使用 Node.js 18 或更高版本：
   ```bash
   node --version  # 应该 >= 18.0.0
   ```

3. **TypeScript 编译错误**
   检查 TypeScript 版本和配置：
   ```bash
   npx tsc --version
   npm run build
   ```

### 调试模式

启用详细日志：

```bash
DEBUG=* npm run dev
```

## 许可证

MIT License

## 参考资料

- [Model Context Protocol 官方文档](https://modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [MCP Streamable HTTP 规范](https://spec.modelcontextprotocol.io/specification/transports/#streamable-http)