使用说明

项目简介

Adonis MCP 是一个 AdonisJS 框架的扩展包，用于快速构建 Model Context Protocol (MCP) 服务器。它允许开发者在 AdonisJS 应用中轻松集成 MCP 协议，通过 Server-Sent Events (SSE) 协议向 LLM 客户端提供资源 (Resources)、工具 (Tools) 和 Prompt 模板 (Prompts) 服务，从而构建功能丰富的 LLM 应用后端。

主要功能点

资源管理: 允许注册和托管各种资源，并通过 URI 访问，为 LLM 提供上下文数据。
工具注册: 支持注册外部工具函数，使 LLM 能够调用这些工具执行特定操作。
Prompt 模板: 提供 Prompt 模板注册功能，定制 LLM 的交互模式。
基于 AdonisJS: 利用 AdonisJS 框架的成熟特性，如路由、配置管理等，简化 MCP 服务器开发。
SSE 传输: 默认使用 Server-Sent Events (SSE) 协议与客户端通信，实现高效的双向数据传输。
易于配置: 提供清晰的配置文件和 API，方便用户自定义 MCP 服务器的行为。

安装步骤

确保已安装 Node.js 和 npm 或 yarn。
创建一个新的 AdonisJS 项目 (如果还没有): 参考 AdonisJS 官方文档。
在 AdonisJS 项目根目录下，运行以下命令安装 Adonis MCP 包:
```
node ace add @7nohe/adonis-mcp
```
该命令会自动安装依赖并在 'config/mcp.ts' 文件中生成默认配置文件。

服务器配置

MCP 服务器是为 MCP 客户端（如 Claude、Cursor 等编辑器插件）提供服务的后端。客户端需要配置 MCP 服务器的连接信息才能正常工作。以下是客户端需要配置的 MCP 服务器信息（JSON 格式）：

{
  "mcpServers": {
    "mymcp": {  // 服务器名称，客户端内唯一标识
      "url": "http://localhost:3333/sse" // MCP 服务器 SSE 连接地址，通常为 {服务器地址}/sse
    }
  }
}

请注意： 这里的 'url' 是指 Adonis MCP 服务器启动后提供的 SSE 接口地址。默认情况下，该地址为 'http://localhost:3333/sse'，端口 '3333' 是 AdonisJS 默认的开发服务器端口，可以根据实际情况修改。'mymcp' 是服务器名称，可以自定义。

基本使用方法

配置 MCP 服务器: 编辑 'config/mcp.ts' 文件，根据需要自定义服务器选项，例如 'ssePath' (SSE 路径), 'messagesPath' (消息接收路径), 'serverOptions' (服务器名称、版本等)。

注册资源、工具和 Prompt: 在 'start/routes.ts' 文件中使用 'mcp.registerRoutes' 方法注册资源、工具和 Prompt。参考以下示例代码：

import mcp from '@7nohe/adonis-mcp/services/main'
import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
import { z } from 'zod'

await mcp.registerRoutes((server) => {
  server.resource(
    'echo', // 资源名称
    new ResourceTemplate('echo://{message}', { list: undefined }), // 资源模板，定义资源 URI 格式
    async (uri, { message }) => ({ // 资源处理函数，根据 URI 参数返回资源内容
      contents: [
        {
          uri: uri.href,
          text: 'Resource echo: ${message}',
        },
      ],
    })
  )

  server.tool(
    'echo', // 工具名称
    { message: z.string() }, // 工具参数 Schema，使用 zod 进行参数校验
    async ({ message }) => ({ // 工具执行函数，处理工具调用并返回结果
      content: [{ type: 'text', text: 'Tool echo: ${message}' }],
    })
  )

  server.prompt(
    'echo', // Prompt 名称
    { message: z.string() }, // Prompt 参数 Schema
    ({ message }) => ({ // Prompt 生成函数，根据参数生成 LLM Prompt 消息
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: 'Please process this message: ${message}',
          },
        },
      ],
    })
  )
})

启动服务器: 在项目根目录下运行以下命令启动 AdonisJS 开发服务器：
```
npm run dev
```
服务器启动后，MCP 客户端即可通过配置的 SSE URL 连接到该服务器，并使用注册的资源、工具和 Prompt。

调试

可以使用 MCP Inspector 工具进行调试，配置 Transport Type 为 'SSE'，URL 为 'http://localhost:3333/sse' (或实际的服务器地址)。

关键词