使用说明

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检查器：

启动服务器 使用HTTP传输：

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

在MCP检查器中，配置连接：
- 连接类型：选择 Direct （用于直接连接到您的服务器）
- 统一资源定位符: http://localhost:3001/mcp （或您配置的端口。， http://localhost:8080/mcp)
- 请求超时: 300000 （默认为5分钟）
- 重置进度超时: True （推荐）
- 最大总超时时间: 60000 （默认为1分钟）
- 检查员代理地址：留空（仅当连接类型为“通过代理”时才需要）
- 代理会话令牌：留空（仅当连接类型为“通过代理”时才需要）
备注：使用时 Direct 连接类型，你可以不需要填写代理地址或代理会话令牌字段。仅在使用时才需要这些 via proxy 连接类型。
连接 -检查器将自动处理会话初始化和SSE流。

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

配置

环境变量

变量	描述	默认值	示例
`TRANSPORT`	运输方式： `stdio` 或 `http`	`stdio`	`TRANSPORT=http npm start` 或 `npm run start:http`
`USE_HTTP`	启用HTTP传输（替代 `TRANSPORT=http`)	`false`	`USE_HTTP=true npm start`
`PORT`	HTTP传输的端口号	`3001`	`PORT=8080 npm run start:http`

运输比较

功能	标准	流式HTTP
用例	本地开发，Claude Desktop	Web客户端，远程访问
连接	进程stdio	HTTP/HTTPS
实时更新	✅	✅ （通过苏格兰和南方能源公司）
会话管理	单会话	多个并发会话
可恢复性	❌	✅ （通过上次事件ID）
CORS支持	不适用	✅
需要端口	❌	✅ （默认值：3001）

文件格式参考

工具

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

位置: 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<{ role: string, content: { type: string, text: string } }> }}
 */
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<string> -阵列
{ key: value } -物体

高级

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

例子

// 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<{ id: number }> }} 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

运作原理

发现：MCP Atom扫描 register/ 递归文件夹
解析：每个 .js 对文件进行分析，以确定：
- JSDoc注释（标题、描述、类型）
- 默认导出功能
- 可选的 autocomplete 出口（资源）
模式生成：JSDoc类型转换为Zod模式
注册：工具、提示和资源会自动注册到MCP服务器
验证：所有输入都根据生成的模式进行验证

最佳实践

始终包含JSDoc：每个文件都需要一个JSDoc块 @param 和 @returns
使用描述性标题：第一行成为工具/提示/资源标题
文档可选参数：使用 ? 在可选字段的类型定义中
尽可能保持函数的纯净：更容易测试和推理
优雅地处理错误：返回有意义的错误消息
使用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传输时：

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

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

认证：如果需要，在MCP路由之前添加身份验证中间件
超文本传输安全协议：使用反向代理（nginx、Caddy）或负载均衡器添加HTTPS
港口安全：确保防火墙只允许必要的端口

后续步骤

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

使用说明

MCP原子

什么是MCP？

为什么选择MCP原子？

主要优势

快速开始

安装

项目结构

你的第一个工具

运行服务器

标准传输（默认）

可流式HTTP传输

配置

环境变量

运输比较

文件格式参考

工具

提示

资源

类型系统

原语

集合

高级

例子

项目结构

运作原理

最佳实践

高级功能

异步函数

返回多个内容项

故障排除

常见问题

HTTP传输问题

生产注意事项

后续步骤

相关 MCP

REST和GraphQL端点自动发现工具

服务器健康监控工具

Django MCP服务器

MCP安全扫描器

金融计算协议服务

MCP工具包