MCP Atom

MCP原子

在几分钟内构建MCP服务器，而不是几小时。 MCP Atom是一个零样板框架，只需读取文件结构和JSDoc注释，即可自动发现、验证和注册您的工具、提示和资源。

什么是MCP？

这 模型上下文协议（MCP） 是一种开放协议，使人工智能助手能够安全地访问外部工具、数据源和功能。将其视为Claude Desktop等人工智能应用程序连接到您的服务、数据库、API和自定义功能的标准化方式。

为什么选择MCP原子？

传统的MCP服务器开发需要：

• ❌ 手动注册每个工具、提示和资源
• ❌ 手工编写JSON模式定义
• ❌ 每个端点的锅炉板代码
• ❌ 将类型定义与实现分开维护

MCP Atom消除了这一切。 只需编写带有JSDoc注释的文件，所有内容都会自动发现、验证和注册。

主要优势

• 🚀 零沸点板：无手册 server.registerTool() 电话
• 📝 JSDoc驱动：从您的评论中自动提取的模式
• 🔍 自动发现：将文件放入文件夹中，它们会自动注册
• ✅ 类型安全：自动生成Zod模式并进行验证
• 🎯 约定胜于配置：文件结构=API结构

快速开始

安装

npm install

项目结构

创建一个 register/ 包含三个子文件夹的文件夹：

register/
├── tools/          # Executable functions
├── prompts/        # Prompt templates
└── resources/      # Data sources (files, APIs, etc.)

你的第一个工具

在中创建文件 register/tools/ 带有JSDoc注释和默认导出。该工具将自动注册到：

• ✅ 基于JSDoc类型的输入验证
• ✅ 输出模式
• ✅ JSDoc的标题和描述
• ✅ 全型安全

运行服务器

MCP Atom支持两种传输模式： 工作室 （默认）和 可流式传输的HTTP.

标准传输（默认）

默认传输使用标准输入/输出，非常适合本地开发和与Claude Desktop等MCP客户端集成。

npm start

或使用MCP检查器进行测试：

npm run start:inspect

可流式HTTP传输

对于基于web的客户端或远程访问，请使用Streamable HTTP传输。这使得：

• HTTP/HTTPS连接
• 服务器发送事件（SSE）用于实时更新
• 具有可恢复性的会话管理
• 基于浏览器的客户端的CORS支持

启用HTTP传输 使用专用脚本：

npm run start:http

或者手动设置环境变量：

# Option 1: Use TRANSPORT environment variable
TRANSPORT=http npm start

# Option 2: Use USE_HTTP flag
USE_HTTP=true npm start

配置端口 （默认值：3001）：

PORT=8080 npm run start:http
# Or with manual env var:
PORT=8080 TRANSPORT=http npm start

服务器将监听 http://localhost:8080/mcp （或您指定的端口，默认值：3001）。

终点：

• POST /mcp -MCP请求（初始化和后续请求）
• GET /mcp -服务器到客户端通知的SSE流
• DELETE /mcp -会话终止

标题：

• mcp-session-id -会话标识符（GET/DELETE需要，初始POST可选）
• last-event-id -用于在断开连接后恢复SSE流

HTTP示例：

# Start server on port 3001 (default)
npm run start:http

# Or with custom port
PORT=8080 npm run start:http

使用HTTP进行测试：

您可以将MCP检查器与HTTP传输一起使用：

# Start server with HTTP transport
npm run start:http

# Then in another terminal, run the inspector
npm run start:inspect

或手动配置MCP检查器：

1. 启动服务器 使用HTTP传输：

   npm run start:http
   # Or with custom port:
   PORT=8080 npm run start:http

1. 在MCP检查器中，配置连接：

- 连接类型：选择 Direct （用于直接连接到您的服务器） - 统一资源定位符: http://localhost:3001/mcp （或您配置的端口。， http://localhost:8080/mcp) - 请求超时: 300000 （默认为5分钟） - 重置进度超时: True （推荐） - 最大总超时时间: 60000 （默认为1分钟） - 检查员代理地址：留空（仅当连接类型为“通过代理”时才需要） - 代理会话令牌：留空（仅当连接类型为“通过代理”时才需要）

备注：使用时 Direct 连接类型，你可以 不 需要填写代理地址或代理会话令牌字段。仅在使用时才需要这些 via proxy 连接类型。

1. 连接 -检查器将自动处理会话初始化和SSE流。

或将任何兼容MCP的客户端连接到 http://localhost:3001/mcp （或您配置的端口）。

配置

环境变量

运输比较

文件格式参考

工具

工具是执行操作的可执行功能。它们接受输入参数并返回结果。

位置: register/tools/*.js

格式:

/**
 * Tool Title - Brief description
 * 
 * @param {{ param1: type1, param2?: type2 }} input
 * @returns {{ result: type }}
 */
export default ({ param1, param2 }) => {
    // Your implementation
    return { result: /* ... */ };
}

可选参数：使用 ? 在类型定义中：

@param {{ name: string, style?: string }} input

复杂类型：支持数组、嵌套对象、联合等：

@param {{ 
    items: string[], 
    config: { timeout: number, retry: boolean },
    status: "active" | "inactive"
}} input

返回元数据：返回数组 [output, ...meta] 以包括附加内容。第一个元素是主要输出，后续元素是元数据项（资源链接、图像等）。

📖 看 register/README.md 查看所有工具类型的详细示例。

提示

提示是为AI助手创建消息的模板生成器。

位置: register/prompts/*.js

格式:

/**
 * Prompt Title - Brief description
 * 
 * @param {{ arg1: type1, arg2?: type2 }} input
 * @returns {{ messages: Array }}
 */
export default ({ arg1, arg2 = "default" }) => {
    return {
        messages: [
            {
                role: "user",
                content: {
                    type: "text",
                    text: `Your prompt text using ${arg1} and ${arg2}`
                }
            }
        ]
    };
}

备注：提示必须返回一个带有 messages 遵循MCP提示格式的数组。

📖 看 register/README.md 查看详细的提示示例。

资源

资源是AI助手可以读取的数据源。它们可以是静态的，也可以是带有参数的动态的。

位置: register/resources/{protocol}/*.js

静态资源:

/**
 * Resource Title - Brief description
 * 
 * @returns {{ ... }}
 */
export default () => {
    return { /* your data */ };
}

带参数的动态资源:

使用文件夹名称 {parameter} 创建参数化资源的语法：

/**
 * Resource Title - Brief description
 * 
 * @param {{ paramName: type }} input
 * @returns {type}
 * @mime text/plain
 */
export default ({ paramName }) => {
    return /* your data */;
}

这创建了一个可在以下位置访问的资源 {protocol}://{path} 从文件夹结构中提取参数。

资源URI结构:

• 文件夹路径： resources/github/repos/{owner}/{repo}.js
• 资源URI: github://repos/{owner}/{repo}
• 注册名称： github-repos-owner-repo

自动补全支持:

添加一个 autocomplete 出口，提供智能完井。每个函数接收 value （电流输入）和 context （使用之前解析的参数），并返回经过过滤的建议数组。

MIME类型：使用指定内容类型 @mime 标签：

/**
 * @mime application/json
 */

📖 看 register/README.md 了解包括自动补全模式在内的详细资源示例。

类型系统

MCP Atom会自动将JSDoc类型转换为Zod模式。支持的类型：

原语

• string, number, boolean, null, any, unknown
• Date （转换为ISO字符串）

集合

• string[] 或 Array -阵列
• { key: value } -物体

高级

• "value1" | "value2" -工会
• { prop?: type } -可选属性
• Promise -承诺（未包装）

例子

// Simple object
@param {{ name: string, age: number }} input

// With optional fields
@param {{ name: string, email?: string }} input

// Nested objects
@param {{ 
    user: { id: string, name: string },
    settings: { theme: "light" | "dark" }
}} input

// Arrays
@param {{ tags: string[], items: Array }} input

// Complex nested structure
@param {{
    config: {
        api: {
            baseUrl: string,
            timeout: number,
            retry: boolean
        },
        features: {
            enabled: boolean,
            options: string[]
        }
    }
}} input

📖 看 register/README.md 更多类型示例和模式。

项目结构

这 register/ 文件夹结构决定您的API结构：

• 工具: register/tools/*.js -每个文件都成为一个工具
• 提示: register/prompts/*.js -每个文件都变成一个提示
• 资源: register/resources/{protocol}/*.js -文件夹结构映射到资源URI

- 静态： resources/config/app.js → config://app - 动态： resources/users/{userId}/profile.js → users://{userId}/profile

运作原理

1. 发现：MCP Atom扫描 register/ 递归文件夹
2. 解析：每个 .js 对文件进行分析，以确定：

- JSDoc注释（标题、描述、类型） - 默认导出功能 - 可选的 autocomplete 出口（资源）

1. 模式生成：JSDoc类型转换为Zod模式
2. 注册：工具、提示和资源会自动注册到MCP服务器
3. 验证：所有输入都根据生成的模式进行验证

最佳实践

1. 始终包含JSDoc：每个文件都需要一个JSDoc块 @param 和 @returns
2. 使用描述性标题：第一行成为工具/提示/资源标题
3. 文档可选参数：使用 ? 在可选字段的类型定义中
4. 尽可能保持函数的纯净：更容易测试和推理
5. 优雅地处理错误：返回有意义的错误消息
6. 使用TypeScript风格的JSDoc：解析器理解TypeScript语法

高级功能

异步函数

所有处理程序都支持async/await。简单使用 async 在函数声明中。

返回多个内容项

工具可以返回一个数组，其中第一个元素是输出，后续元素是元数据（资源链接、图像等）。

故障排除

常见问题

“未找到默认导出”：每个文件都必须有 export default

“未找到JSDoc”：每个文件都需要一个JSDoc注释块

类型分析错误：检查JSDoc语法是否与示例匹配

资源未找到：验证文件夹结构是否匹配 resources/{protocol}/...

HTTP传输问题

“端口已在使用中”：使用以下命令更改端口 PORT=8080 npm run start:http

“CORS错误”：服务器默认配置为启用CORS(origin: "*").对于生产，考虑限制原产地。

“未找到会话”：确保您正在发送 mcp-session-id 初始化后GET/DELETE请求的标头

“连接被拒绝”：验证服务器是否正在运行，端口是否与客户端配置匹配

生产注意事项

在生产环境中使用HTTP传输时：

1. CORS配置默认的CORS设置允许所有来源(origin: "*").在生产中限制此操作：

   // In index.js, update the CORS configuration
   app.use(cors({
     origin: process.env.ALLOWED_ORIGINS?.split(',') || ['https://yourdomain.com'],
     // ... other options
   }));

1. 认证：如果需要，在MCP路由之前添加身份验证中间件

1. 超文本传输安全协议：使用反向代理（nginx、Caddy）或负载均衡器添加HTTPS

1. 港口安全：确保防火墙只允许必要的端口

后续步骤

• 📖 看 register/README.md 有关所有文件类型的详细示例，请参阅实际代码
• 🔧 结账 builderBot/readme.md 内部实施细节
• 📚 阅读 MCP规范 有关协议详细信息