# @claude-flow/mcp 中文文档

规范地址：https://npmcn.com/package/%40claude-flow/mcp/

版本：3\.1\.7
npm 元数据更新时间：2026-11-09T08:35:57.459Z
中文译文更新时间：2026-11-10T00:05:22.098Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40claude-flow/mcp
原文对照：https://npmcn.com/package/%40claude-flow/mcp/?lang=original
项目主页：https://ruv.io/
源码仓库：https://github.com/ruvnet/ruflo

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：467 kB，74 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2026-01-06T21:45:54.593Z
- 最新版本发布：2026-11-09T08:35:57.258Z
- 近 30 天下载量：28906（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

独立的 MCP(模式上下文协议)服务器 - stdio/http/websocket 传输,连接集合,工具注册

## 安装

```sh
npm install @claude-flow/mcp
```

也可以使用：`pnpm add @claude-flow/mcp`、`yarn add @claude-flow/mcp`、`bun add @claude-flow/mcp`

## README

# @ claude- flow/ mcp

![Animated diagram: an MCP client request travels through a transport and the MCPServer to the ToolRegistry and the tool handler](https://raw.githubusercontent.com/ruvnet/ruflo/main/v3/@claude-flow/mcp/assets/mcp-flow.svg)

**@ claude- flow/ mcp** ——一个独立的模型上下文协议服务器:stdio,HTTP和WebSocket传输,一个经过计划检查的工具注册,资源,提示和任务.

**支持的环境 :** 节点.js 20+ → 无害环境管理 → Linux, macOS, Windows (纯 JavaScript)

## 快速启动

```bash
npm install @claude-flow/mcp
```

```js
import { createToolRegistry, defineTool } from '@claude-flow/mcp';

const logger = { debug() {}, info() {}, warn: console.warn, error: console.error };
const registry = createToolRegistry(logger);
registry.register(defineTool('echo', 'Echo the input text', {
  type: 'object', properties: { text: { type: 'string' } }, required: ['text'],
}, async ({ text }) => ({ echoed: text })));
console.log(registry.getToolNames());
const result = await registry.execute('echo', { text: 'hi' });
console.log(result.isError ?? false, result.content[0].text);
```

预期产出:

```text
[ 'echo' ]
false {
  "echoed": "hi"
}
```

用于 [`@claude-flow/cli`](https://www.npmjs.com/package/@claude-flow/cli),它在这个服务器上为 Ruflo 工具服务.

[![npm version](https://img.shields.io/npm/v/@claude-flow/mcp.svg)](https://www.npmjs.com/package/@claude-flow/mcp) [![npm downloads](https://img.shields.io/npm/dm/@claude-flow/mcp.svg)](https://www.npmjs.com/package/@claude-flow/mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/) [![MCP 2025-11-25](https://img.shields.io/badge/MCP-2025--11--25-blue.svg)](https://modelcontextprotocol.io/) [![Standalone](https://img.shields.io/badge/Module-Standalone-green.svg)](https://github.com/ruvnet/claude-flow)

> **MCP 2025-11-25 协作者** - 独立模式上下文协议服务器安装,并配备全部资源、提示和任务支持

## 特征

-   **MCP 2025-11-25 协作者** - 全面规格支持
-   **高性能服务器** - <400ms启动时间
-   **多重运输** - Stdio、HTTP、WebSocket、进行中
-   **资源** - 列表, 读取, 用缓存订阅
-   **提示** - 有参数和嵌入式资源的模板
-   **任务** - 有进展和取消的同步业务
-   **倾斜** - 大型数据集基于光标的平面图
-   **连接集合** - 最大10个连接,可配置
-   **快速工具注册** - O(1) 查询, < 10ms登记
-   **会话管理** - 超时处理、认证
-   **警卫** - CORS、Helmet、认证信条
-   **无依赖** - 没有@claude-flow/\* 依赖关系

## 安装

```bash
npm install @claude-flow/mcp
```

## 快速启动

```typescript
import { quickStart, defineTool } from '@claude-flow/mcp';

// Create and start server
const server = await quickStart({
  transport: 'stdio',
  name: 'My MCP Server',
});

// Register custom tools
server.registerTool(defineTool(
  'greet',
  'Greet a user',
  {
    type: 'object',
    properties: {
      name: { type: 'string', description: 'User name' }
    },
    required: ['name']
  },
  async ({ name }) => ({ message: `Hello, ${name}!` })
));

// Start listening
await server.start();
```

## 运输

### Stdio (默认)

```typescript
import { createMCPServer } from '@claude-flow/mcp';

const server = createMCPServer({
  transport: 'stdio',
  name: 'Stdio Server',
}, logger);

await server.start();
```

### HTTP 密码

```typescript
const server = createMCPServer({
  transport: 'http',
  host: 'localhost',
  port: 3000,
  corsEnabled: true,
  corsOrigins: ['http://localhost:8080'],
  auth: {
    enabled: true,
    method: 'token',
    tokens: ['secret-token'],
  },
}, logger);

await server.start();
// Server at http://localhost:3000
// WebSocket at ws://localhost:3000/ws
```

### 网络安全套

```typescript
const server = createMCPServer({
  transport: 'websocket',
  host: 'localhost',
  port: 3001,
  maxConnections: 100,
  heartbeatInterval: 30000,
}, logger);

await server.start();
// WebSocket at ws://localhost:3001/ws
```

## 工具登记

```typescript
import { createToolRegistry, defineTool } from '@claude-flow/mcp';

const registry = createToolRegistry(logger);

// Register tool
registry.register({
  name: 'calculate',
  description: 'Perform calculations',
  inputSchema: {
    type: 'object',
    properties: {
      expression: { type: 'string' }
    }
  },
  handler: async ({ expression }) => {
    return { result: eval(expression) };
  },
  category: 'math',
  tags: ['calculator'],
});

// Execute tool
const result = await registry.execute('calculate', { expression: '2 + 2' });

// Search tools
const mathTools = registry.getByCategory('math');
const stats = registry.getStats();
```

## 会话管理

```typescript
import { createSessionManager } from '@claude-flow/mcp';

const sessions = createSessionManager(logger, {
  maxSessions: 100,
  sessionTimeout: 30 * 60 * 1000, // 30 minutes
});

// Create session
const session = sessions.createSession('http');

// Initialize with client info
sessions.initializeSession(session.id, {
  protocolVersion: '2024-11-05', // MCP spec: YYYY-MM-DD string
  capabilities: { tools: { listChanged: true } },
  clientInfo: { name: 'Claude', version: '1.0' },
});

// Get metrics
const metrics = sessions.getSessionMetrics();
// { total: 1, active: 1, authenticated: 0, expired: 0 }
```

## 连接池

```typescript
import { createConnectionPool } from '@claude-flow/mcp';

const pool = createConnectionPool({
  maxConnections: 10,
  minConnections: 2,
  idleTimeout: 30000,
  acquireTimeout: 5000,
}, logger, 'http');

// Acquire connection
const conn = await pool.acquire();

// Use connection...

// Release back to pool
pool.release(conn);

// Get stats
const stats = pool.getStats();
// { totalConnections: 5, idleConnections: 4, busyConnections: 1, ... }
```

## API 参考

### 服务器

```typescript
interface IMCPServer {
  start(): Promise<void>;
  stop(): Promise<void>;
  registerTool(tool: MCPTool): boolean;
  registerTools(tools: MCPTool[]): { registered: number; failed: string[] };
  getHealthStatus(): Promise<{ healthy: boolean; error?: string; metrics?: Record<string, number> }>;
  getMetrics(): MCPServerMetrics;
  getSessions(): MCPSession[];
  getSession(sessionId: string): MCPSession | undefined;
  terminateSession(sessionId: string): boolean;
}
```

### 工具

```typescript
interface MCPTool<TInput = unknown, TOutput = unknown> {
  name: string;
  description: string;
  inputSchema: JSONSchema;
  handler: (input: TInput, context?: ToolContext) => Promise<TOutput>;
  category?: string;
  tags?: string[];
  cacheable?: boolean;
  cacheTTL?: number;
  timeout?: number;
}
```

### 运输

```typescript
interface ITransport {
  readonly type: TransportType;
  start(): Promise<void>;
  stop(): Promise<void>;
  onRequest(handler: RequestHandler): void;
  onNotification(handler: NotificationHandler): void;
  sendNotification?(notification: MCPNotification): Promise<void>;
  getHealthStatus(): Promise<TransportHealthStatus>;
}
```

## 内建工具

服务器自动注册这些系统工具 :

| 工具 | 说明 |
| --- | --- |
| `system/info` | 获取服务器信息 |
| `system/health` | 获得健康状况 |
| `system/metrics` | 获取服务器参数 |
| `tools/list-detailed` | 列出所有详细工具 |

## 资源(MCP 2025-11-25)

```typescript
import { createMCPServer, createTextResource } from '@claude-flow/mcp';

const server = createMCPServer({ transport: 'stdio' }, logger);
const resourceRegistry = server.getResourceRegistry();

// Register a text resource
const { resource, handler } = createTextResource(
  'file://readme.txt',
  'README',
  'Welcome to the application!',
  { mimeType: 'text/plain' }
);
resourceRegistry.registerResource(resource, handler);

// Register with custom handler
resourceRegistry.registerResource(
  {
    uri: 'db://users/{id}',
    name: 'User Data',
    description: 'Get user by ID',
    mimeType: 'application/json',
  },
  async (uri) => {
    const id = uri.split('/').pop();
    const user = await fetchUser(id);
    return [{ uri, mimeType: 'application/json', text: JSON.stringify(user) }];
  }
);

// Subscribe to updates
resourceRegistry.subscribe('file://readme.txt', (uri, content) => {
  console.log('Resource updated:', uri);
});
```

## 提示(MCP 2025-11-25)

```typescript
import { createMCPServer, definePrompt, textMessage, interpolate } from '@claude-flow/mcp';

const server = createMCPServer({ transport: 'stdio' }, logger);
const promptRegistry = server.getPromptRegistry();

// Define a prompt with arguments
const codeReviewPrompt = definePrompt(
  'code_review',
  'Review code for quality and best practices',
  async (args) => [
    textMessage('user', `Please review this ${args.language} code:\n\n${args.code}`),
  ],
  {
    title: 'Code Review',
    arguments: [
      { name: 'code', description: 'The code to review', required: true },
      { name: 'language', description: 'Programming language', required: false },
    ],
  }
);

promptRegistry.register(codeReviewPrompt);

// Get prompt with arguments
const result = await promptRegistry.get('code_review', {
  code: 'function hello() { return "world"; }',
  language: 'JavaScript',
});
```

## 任务(MCP 2025-11-25)

```typescript
import { createMCPServer } from '@claude-flow/mcp';

const server = createMCPServer({ transport: 'stdio' }, logger);
const taskManager = server.getTaskManager();

// Create a long-running task
const taskId = taskManager.createTask(async (reportProgress, signal) => {
  for (let i = 0; i <= 100; i += 10) {
    if (signal.aborted) throw new Error('Task cancelled');

    reportProgress({
      progress: i,
      total: 100,
      message: `Processing... ${i}%`,
    });

    await new Promise(r => setTimeout(r, 100));
  }

  return { success: true, processedItems: 100 };
});

// Get task status
const status = taskManager.getTask(taskId);

// Wait for completion
const result = await taskManager.waitForTask(taskId);

// Cancel a task
taskManager.cancelTask(taskId, 'User requested cancellation');
```

## MCP 支持的方法

| 方法 | 说明 |
| --- | --- |
| `initialize` | 初始化连接 |
| `tools/list` | 列出可用的工具 |
| `tools/call` | 执行工具 |
| `resources/list` | 用页形列出资源 |
| `resources/read` | 读取资源内容 |
| `resources/subscribe` | 订阅更新 |
| `resources/unsubscribe` | 从更新中取消订阅 |
| `prompts/list` | 带有页标的列表提示符 |
| `prompts/get` | 获取参数的快捷键 |
| `tasks/status` | 获取任务状态 |
| `tasks/cancel` | 取消运行中的任务 |
| `completion/complete` | 自动完成参数 |
| `logging/setLevel` | 设置日志级别 |
| `ping` | 保持存活状态 |

## 绩效目标

| 度量衡 | 目标 |
| --- | --- |
| 服务器启动 | < 400 分钟 |
| 工具注册 | < 10 分钟 |
| 工具执行间接费用 | < 50 分钟 |
| 连接获取 | < 5 ms 时 |
| 连接释放 | < 1 分钟 |

## 警卫

### 认证

```typescript
const server = createMCPServer({
  auth: {
    enabled: true,
    method: 'token',
    tokens: ['your-secret-token'],
  },
}, logger);
```

### (简体中文)

```typescript
const server = createMCPServer({
  transport: 'http',
  corsEnabled: true,
  corsOrigins: ['https://your-domain.com'],
}, logger);
```

## 错误代码

```typescript
const ErrorCodes = {
  PARSE_ERROR: -32700,
  INVALID_REQUEST: -32600,
  METHOD_NOT_FOUND: -32601,
  INVALID_PARAMS: -32602,
  INTERNAL_ERROR: -32603,
  SERVER_NOT_INITIALIZED: -32002,
  AUTHENTICATION_REQUIRED: -32001,
};
```

## 许可证

麻省理工学院

* * *

由 [尔 紫外线](https://ruv.io/) • 妇女 [卢夫.io](https://ruv.io/) • 妇女 [来源](https://github.com/ruvnet/ruflo/tree/main/v3/@claude-flow/mcp)

## 常见问题

### @claude-flow/mcp 是什么？

独立的 MCP\(模式上下文协议\)服务器 - stdio/http/websocket 传输,连接集合,工具注册

### 如何安装 @claude-flow/mcp？

在项目目录运行 npm install @claude-flow/mcp，或使用 pnpm add / yarn add / bun add。

### @claude-flow/mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @claude-flow/mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @claude-flow/mcp 可以商用吗？

@claude-flow/mcp 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @claude-flow/mcp 的下载量有多少？

根据 npm 官方下载统计，@claude-flow/mcp 在 2026/10/10 – 2026/11/08 这 30 天内被下载 28,906 次，日均约 964 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @claude-flow/mcp 还在维护吗？

最新版本 3\.1\.7 发布于 2026/11/09（今天）；至今共发布 14 个版本，其中过去 12 个月发布了 14 个；首次发布于 2026/01/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。