使用说明

项目简介

effect-mcp 是一个基于 Model Context Protocol (MCP) 协议的服务器端实现，它使用 Effect TypeScript 库构建，旨在为 AI 模型提供结构化的上下文信息和功能调用能力。该项目提供了类型安全、功能强大的 MCP 服务器框架，支持资源、工具和 Prompt 模板的管理，并使用 JSON-RPC 协议进行通信。

主要功能点

资源管理 (Resources): 虽然示例中没有显式资源管理，但代码结构预留了资源处理的接口，MCP 服务器具备扩展资源管理能力的基础。
工具注册和执行 (Tools): 支持注册和调用外部工具，示例中定义了 'Echo' 和 'Calculator' 工具，展示了工具的注册和执行机制。
Prompt 模板 (Prompts): 支持定义和管理 Prompt 模板，示例中定义了 'Echo' 和 'Greet' 等 Prompt，允许客户端通过名称和参数获取 Prompt 消息。
JSON-RPC 通信: 使用 JSON-RPC 协议与客户端进行通信，处理客户端的请求和发送响应。
多种传输协议: 实现了 Stdio 和 SSE 传输协议，方便在不同环境中使用。
会话管理和能力声明: 服务器在初始化时声明自身的能力，并处理客户端的初始化请求。

安装步骤

克隆仓库:

git clone https://github.com/ghardin1314/effect-mcp.git
cd effect-mcp

安装依赖: 确保你已安装 pnpm 包管理器。如果未安装，请先安装 pnpm：
```
npm install -g pnpm
```
然后安装项目依赖：
```
pnpm install
```
构建项目:
```
pnpm build
```

服务器配置

MCP 客户端需要配置服务器的启动命令才能连接到 effect-mcp 服务器。以下是针对不同 'examples/server' 示例的配置信息。

1. Stdio Server 配置 (examples/server/src/stdio.ts):

用于通过标准输入/输出流 (stdio) 与服务器通信。

{
  "serverName": "Echo",
  "command": "node",
  "args": ["./examples/server/dist/stdio.js"]
}

参数注释:

'"serverName"': 服务器名称，例如 "Echo"。
'"command"': 启动服务器的命令，这里是 'node' (假设 node.js 环境已配置)。
'"args"': 命令参数，指定要执行的服务器 JavaScript 文件路径 './examples/server/dist/stdio.js'。请确保在运行客户端之前已经构建 (build) 过项目，'dist' 目录已经生成。

2. SSE Server 配置 (examples/server/src/sse.ts):

用于通过 HTTP SSE (Server-Sent Events) 与服务器通信。

首先需要启动 SSE 服务器，在仓库根目录下，执行：

node examples/server/dist/sse.js

服务器默认监听 3001 端口。

客户端配置 (连接到 SSE 服务器的 '/messages' 接口):

{
  "serverName": "Echo",
  "transport": "sse",
  "url": "http://localhost:3001/messages?sessionId={sessionId}"
}

参数注释:

'"serverName"': 服务器名称，例如 "Echo"。
'"transport"': 传输协议类型，这里是 '"sse"'。
'"url"': SSE 服务器的 URL，指向消息接收接口，包含 'sessionId' 参数，用于服务器端会话管理 (具体 'sessionId' 如何生成和传递可能需要查阅客户端库文档)。

注意: SSE 配置是一个示例，实际 MCP 客户端库可能需要更详细的 SSE 连接配置，请参考客户端库的文档进行配置。

基本使用方法

启动服务器: 根据选择的传输协议 (stdio 或 sse) 启动相应的服务器示例。例如，对于 Stdio 服务器，直接运行 'node examples/server/dist/stdio.js'。对于 SSE 服务器，运行 'node examples/server/dist/sse.js'。
配置 MCP 客户端: 根据你使用的 MCP 客户端库，配置连接到 effect-mcp 服务器。客户端需要指定服务器的启动命令 (stdio) 或 URL (sse)，以及服务器的名称等信息。参考上述 “服务器配置” 部分。
使用客户端 API: MCP 客户端通常会提供 API 来调用 MCP 服务器的功能，例如：
- 'initialize()': 初始化连接。
- 'listToolsAwait()': 列出服务器提供的工具。
- 'callToolAwait(toolName, arguments)': 调用指定名称的工具并传入参数。
- 'listPromptsAwait()': 列出服务器提供的 Prompt 模板。
- 'getPromptAwait(promptName, arguments)': 获取指定 Prompt 模板的消息内容。
请参考客户端库的文档，了解详细的 API 使用方法。'examples/client' 目录下提供了客户端使用的示例代码，可以参考学习。

示例 - 使用 Stdio 客户端连接到 Stdio 服务器 (参考 examples/client/src/stdio.ts):

import { McpClient, StdioClientTransport } from "@effect-mcp/client";
import { Command } from "@effect/platform";
import { NodeContext, NodeRuntime } from "@effect/platform-node";
import { Effect, Logger, LogLevel } from "effect";

// 定义服务器启动命令
const command = Command.make("node", "./dist/stdio.js").pipe(
  Command.workingDirectory(serverCwd) // 设置工作目录为服务器代码目录
);

// 创建 MCP 客户端 Layer
const client = McpClient.layer({
  name: "Echo", // 服务器名称，与服务器配置一致
  version: "1.0.0",
});

// 创建 Stdio 传输 Layer
const transport = StdioClientTransport.layer(command);

// 定义客户端程序
const program = Effect.gen(function* () {
  const client = yield* McpClient.McpClient;

  yield* client.initialize; // 初始化连接

  const tools = yield* client.listToolsAwait({}); // 列出工具
  const prompts = yield* client.listPromptsAwait({}); // 列出 Prompt 模板

  return {
    prompts,
    tools,
  };
}).pipe(Effect.flatMap((result) => Effect.logDebug(JSON.stringify(result))));

// 运行客户端程序
program.pipe(
  Effect.provide(client),
  Effect.provide(transport),
  Effect.provide(NodeContext.layer),
  Logger.withMinimumLogLevel(LogLevel.Debug),
  Effect.scoped,
  NodeRuntime.runMain
);

这个示例代码展示了如何配置 Stdio 客户端，连接到 Stdio 服务器，并调用 'listToolsAwait' 和 'listPromptsAwait' 方法来获取服务器提供的工具和 Prompt 模板信息。

注意事项

开发阶段: 该项目处于积极开发阶段，可能不稳定，不建议用于生产环境。
MCP 协议早期: Model Context Protocol 本身也处于早期开发阶段，协议可能会发生变化。
错误处理和测试: 项目在错误处理和测试方面还有待完善，后续版本会增加。

请根据你的具体需求和 MCP 客户端库的文档，调整配置和使用方法。

关键词