开发
本指南介绍如何为 1MCP Agent 设置开发环境、从源码构建以及为项目做出贡献。
先决条件
从源码安装
克隆仓库
bashgit clone https://github.com/1mcp-app/agent.git cd agent安装依赖
bashpnpm install构建项目
bashpnpm build运行开发服务器
bash# 首先复制示例环境文件 cp .env.example .env # 然后运行开发服务器 pnpm dev
开发工作流
可用脚本
bash
# 开发模式，自动重建和测试配置
pnpm dev
# 构建项目
pnpm build
# 开发监视模式
pnpm watch
# 代码检查
pnpm lint
pnpm lint:fix
# 类型检查
pnpm typecheck
# 测试
pnpm test:unit
pnpm test:unit:watch
pnpm test:unit:coverage
pnpm test:e2e
pnpm test:e2e:watch
pnpm test:e2e:coverage
# 使用 MCP Inspector 调试
pnpm inspector
# 其他实用工具
pnpm clean # 清理构建产物
pnpm format # 使用 Prettier 格式化代码
pnpm format:check # 检查代码格式
# 二进制文件和打包
pnpm sea:build # 创建 SEA 包
pnpm sea:binary # 为当前平台构建二进制文件
pnpm build:binaries # 构建所有平台二进制文件
# 文档
pnpm docs:dev # 启动 VitePress 开发服务器
pnpm docs:build # 构建文档
pnpm docs:preview # 预览构建的文档开发环境设置
在开始开发之前，复制环境模板：
bash
cp .env.example .env.env 文件包含开发特定的配置，包括：
ONE_MCP_LOG_LEVEL=debug- 开发增强日志记录ONE_MCP_LOG_FILE=./build/1mcp.log- 日志文件位置ONE_MCP_PORT=3051- 开发服务器端口ONE_MCP_ENABLE_AUTH=true- 启用身份验证ONE_MCP_ENABLE_ASYNC_LOADING=true- 启用异步加载ONE_MCP_CONFIG_DIR=./config- 开发自定义配置目录
架构概述
1MCP 遵循分层架构，具有清晰的关注点分离：
- 传输层 (
src/transport/) - HTTP/SSE 和 STDIO 协议实现 - 应用层 (
src/commands/) - CLI 命令和面向用户的功能 - 核心层 (
src/core/) - 服务器管理、能力聚合、异步加载 - 支持服务 (
src/services/,src/config/,src/auth/) - 配置、身份验证、健康监控
关键设计模式
- 单例模式：ServerManager、McpConfigManager、AgentConfigManager 使用
getInstance() - 工厂模式：TransportFactory 创建特定协议的传输
- 代理模式：1MCP 通过统一接口聚合多个 MCP 服务器
- 观察者模式：事件驱动的加载与实时能力更新
核心组件
- ServerManager (
src/core/server/) - 管理 MCP 服务器生命周期和连接 - McpConfigManager (
src/config/) - 配置管理和热重载 - TransportFactory (
src/transport/) - 创建 HTTP/STDIO 传输实例 - CapabilitiesManager (
src/core/capabilities/) - 聚合来自多个服务器的工具/资源
调试
使用 MCP Inspector
MCP Inspector 作为包脚本可用：
bash
pnpm inspectorInspector 将提供一个 URL 来在浏览器中访问调试工具。
调试和源码映射
此项目使用 source-map-support 来增强堆栈跟踪。当您运行服务器时，堆栈跟踪将引用原始 TypeScript 源文件而不是编译的 JavaScript。这使得调试更加容易，因为错误位置和行号将与您的源代码匹配。
无需额外设置——默认启用。如果您看到堆栈跟踪，它将指向 .ts 文件和正确的行号。🗺️
测试
测试配置隔离
测试 "mcp" 子命令时，始终在此项目内使用临时配置，不要破坏用户的默认配置：
bash
# 使用临时配置目录
ONE_MCP_CONFIG_DIR=.tmp-test node build/index.js mcp add test-server -- echo '{"jsonrpc":"2.0"}'
# 或使用 --config-dir 标志
node build/index.js --config-dir .tmp-test mcp add test-server -- echo '{"jsonrpc":"2.0"}'配置目录功能允许项目特定配置，这对于测试不同设置而不影响全局配置非常有用。
环境和配置
- 不要直接使用 ONEMCP* 环境变量，而是使用 yargs 的选项，环境变量将加载到选项中
- 修改文档后应使用
pnpm docs:build验证文档
二进制文件开发和测试
- 使用
pnpm sea:build创建单可执行应用程序 (SEA) 包 - 使用
pnpm sea:binary为当前平台测试二进制文件或平台特定脚本 - 二进制文件开发需要 Node.js SEA 支持和 postject 注入
- SEA 配置在
sea-config.json中
测试基础设施
- 单元测试：与源代码共置的
.test.ts文件 - E2E 测试：位于
test/e2e/中，具有专用配置 - 模拟实用工具：使用
test/unit-utils/MockFactories.ts进行一致的测试数据 - 测试隔离：每个测试都应清理资源且不影响其他测试
CLI 命令开发
添加新的 CLI 命令时：
- 命令结构：遵循
src/commands/中的现有模式 - Yargs 集成：使用适当的命令构建器和验证
- 错误处理：实现用户友好的错误处理
- 测试：为命令功能创建单元测试和 E2E 测试
- 文档：更新帮助文本并考虑文档影响
MCP 命令示例
mcp add <name>- 添加新的 MCP 服务器配置mcp status [name]- 显示服务器状态和健康mcp list- 列出所有配置的服务器及其标签和状态
MCP 服务器集成模式
服务器生命周期管理
- MCP 服务器通过
src/core/server/ServerManager.ts作为子进程管理 - 使用异步加载优雅处理启动缓慢的服务器
- 使用进程信号处理器在关闭时实现适当的清理
传输抽象
- HTTP 传输通过 SSE（服务器发送事件）支持多个客户端
- STDIO 传输提供直接的 MCP 协议通信
- 标签过滤允许向不同客户端选择性暴露服务器
配置管理
- 在不停止活动连接的情况下热重载配置
- 支持所有配置选项的环境变量覆盖
- 在应用更改之前使用 Zod 验证配置模式
测试 MCP 集成
测试 MCP 功能时：
bash
# 使用临时配置测试特定 MCP 服务器
ONE_MCP_CONFIG_DIR=.tmp-test node build/index.js mcp add test-server -- echo '{"jsonrpc":"2.0"}'
# 使用不同客户端类型测试 HTTP 传输
curl "http://localhost:3050/mcp?app=cursor&tags=filesystem"
# 使用标签过滤测试 STDIO 传输
echo '{"jsonrpc":"2.0","method":"initialize","params":{}}' | node build/index.js --transport stdio --tag-filter filesystem贡献
欢迎贡献！请阅读我们的 CONTRIBUTING.md 了解我们的行为准则以及向我们提交拉取请求的过程。
开发指南
- 始终使用 pnpm 脚本如 "lint"、"typecheck"、"build" 和 "test" 来验证实现
- 避免在 TypeScript 中使用 "any" 关键字
- 遵循安全优先实践，使用 Zod 模式进行适当的输入清理
- 使用现有实用函数进行常见操作（分页、过滤、错误处理）
- 实现具有特定错误类型和优雅降级的适当错误处理
- 对核心管理器使用单例模式，对对象创建使用工厂模式
- 遵循具有清晰关注点分离的分层架构
- 使用 Vitest 进行测试，与源代码共置单元测试 (
.test.ts) 和test/e2e/中的专用 E2E 测试基础设施 - 使用标签验证实现具有基于范围授权的 OAuth 2.1 身份验证
- 使用 Winston 结构化日志记录和条件日志记录函数（
debugIf、infoIf、warnIf） - 遵循文件系统监视器的配置管理热重载模式
- 为长时间运行的进程和子进程管理实现适当的资源清理
- 发现新错误时，始终在修复前编写正式的单元测试来重现它