Synergy/DE MCP服务器
一个只读的模型上下文协议（MCP）服务器，它将Synergy/DE文档作为工具和资源公开，使从Cursor和其他MCP客户端搜索、检索和浏览文档主题变得容易。
特性
- 全文搜索 跨Synergy/DE文档，并进行相关性评分
- 主题检索 分块内容针对LLM消费进行了优化
- 相关主题导航 （上一页、下一页、父页和相关链接）
- 章节浏览 按类别查找主题
- 版本支持 适用于不同的Synergy/DE文档版本
- 智能缓存 尽量减少网络请求并提高性能
- 在线和本地 文档支持（混合模式可用）
- MCP资源 用于在Cursor中直接访问主题和章节
先决条件
- Node.js 18.0.0或更高版本 （提供内置
fetch用于HTTP请求的API） - npm 或 pnpm 包管理器
- 光标 （用于MCP集成）或另一个MCP兼容客户端
安装
- 克隆此存储库：
git clone https://github.com/h0ck3ystyx/synergyde-mcp.git
cd synergyde-mcp- 安装依赖项：
npm install
# or
pnpm install- 构建项目：
npm run build- 配置环境变量 （可选）：
cp .env.example .env
# Edit .env with your preferences配置
服务器可以通过环境变量进行配置。所有变量都是可选的，并且都有合理的默认值。
环境变量
| 变量 | 描述 | 默认值 | 必填 |
|---|---|---|---|
SYNERGYDE_DOC_BASE_URL | 在线文档的基本URL | https://www.synergex.com/docs/ | 没有 |
SYNERGYDE_DOC_DEFAULT_VERSION | 要使用的默认文档版本 | "latest" | 没有 |
SYNERGYDE_LOCAL_DOC_PATH | 本地文档目录的路径 | （无） | 否 |
SYNERGYDE_CACHE_DIR | 用于缓存已解析主题的目录 | ./cache | 没有 |
LOG_LEVEL | 日志记录级别： debug, info, warn，或 error | info | 没有 |
配置详情
SYNERGYDE_DOC_BASE_URL：Synergy/DE文档网站的基本URL。应以尾随斜线结尾（如果缺少，则自动添加）。
SYNERGYDE_DOC_DEFAULT_VERSION：在工具调用中未指定版本时使用的默认版本。常见值："latest","v111","v112"等等。
SYNERGYDE_LOCAL_DOC_PATH：如果提供，则启用本地文档支持。路径必须可读，并指向包含本地文档文件的目录。设置后，服务器以“混合”模式运行，更喜欢本地文档，但如果在本地找不到主题，则会退回到在线文档。
SYNERGYDE_CACHE_DIR：解析后的主题缓存在磁盘上的目录。如果目录不存在，将自动创建。缓存的主题存储为按版本和主题ID键入的JSON文件。
LOG_LEVEL：控制日志记录的详细程度。使用debug关于开发过程中的详细信息，info对于正常操作，warn仅用于警告，或error仅用于错误。
示例 .env 文件
# Use online documentation with latest version
SYNERGYDE_DOC_BASE_URL=https://www.synergex.com/docs/
SYNERGYDE_DOC_DEFAULT_VERSION=latest
# Cache directory (relative to project root)
SYNERGYDE_CACHE_DIR=./cache
# Logging level
LOG_LEVEL=info用法
运行服务器
服务器使用stdio传输，设计为由MCP客户端启动：
npm start服务器将：
- 初始化配置
- 连接到stdio传输
- 等待来自客户端的MCP请求
注： 该服务器旨在由MCP客户端（如Cursor）运行，而不是直接运行。手动运行它将导致它等待stdin上的输入。
光标MCP配置
将服务器添加到Cursor MCP配置中。配置文件的位置取决于您的设置：
- 全局配置:
~/.cursor/mcp.json（macOS/Linux）或%APPDATA%\Cursor\mcp.json（Windows） - 项目配置:
.cursor/mcp.json在项目根目录中
基本配置
{
"mcpServers": {
"synergyde-docs": {
"command": "node",
"args": ["/absolute/path/to/synergyde-mcp/dist/server.js"],
"env": {
"SYNERGYDE_DOC_DEFAULT_VERSION": "latest"
}
}
}
}本地文档的高级配置
{
"mcpServers": {
"synergyde-docs": {
"command": "node",
"args": ["/absolute/path/to/synergyde-mcp/dist/server.js"],
"env": {
"SYNERGYDE_DOC_BASE_URL": "https://www.synergex.com/docs/",
"SYNERGYDE_DOC_DEFAULT_VERSION": "latest",
"SYNERGYDE_LOCAL_DOC_PATH": "/path/to/local/docs",
"SYNERGYDE_CACHE_DIR": "/path/to/cache",
"LOG_LEVEL": "info"
}
}
}
}重要提示： 为服务器可执行文件和配置中的任何文件路径使用绝对路径。
可用工具
服务器公开了以下MCP工具：
search_docs
使用全文搜索搜索文档主题。
参数：
query（必填）：搜索查询字符串version（可选）：文档版本（默认为配置的默认值）section（可选）：按节名称筛选limit（可选）：最大结果数（默认值：10）
退货： 具有相关性得分的搜索结果数组
get_topic
按ID或URL获取文档主题。
参数：
topic_id（可选）：主题ID（例如。，"Language/variables.htm")url（可选）：主题页的完整URLversion（可选）：文档版本max_chunks（可选）：要返回的最大块数（默认值：3，0=无限制）
退货： 具有分块内容的主题对象
get_related_topics
获取给定主题的相关主题（上一个、下一个、父级、相关链接）。
参数：
topic_id（必填）：主题IDversion（可选）：文档版本
退货： 带有导航链接的RelatedTopics对象
list_section_topics
在文档部分列出所有主题。
参数：
section（必填）：节名称（例如。，"Language","Reference")version（可选）：文档版本limit（可选）：最大主题数（默认值：50）
退货： 主题摘要数组
describe_docs
获取有关可用文档的元数据。
参数： 无
退货： 带有版本、节和源类型的DocMetadata
可用资源
服务器公开以下MCP资源：
主题资源
URI： synergyde:topic/{topic_id} 或 synergyde:topic/{version}/{topic_id}
返回包含元数据的文档主题的纯文本内容。内容限制为约8k个令牌，以适应LLM上下文窗口。
示例：
synergyde:topic/Language/variables.htmsynergyde:topic/latest/Language/variables.htmsynergyde:topic//Language/variables.htm（明确无版本）
部门资源
URI： synergyde:section/{version}/{section}
返回包含标题、ID、URL和摘要的节中主题的纯文本索引。内容限制为约8k个令牌。
示例：
synergyde:section/latest/Languagesynergyde:section/v111/Reference
错误处理
所有工具和资源都以以下格式返回结构化错误有效载荷：
{
code: string; // Error code (e.g., "TOPIC_NOT_FOUND", "NETWORK_ERROR")
message: string; // Human-readable error message
details?: { // Additional context
topic_id?: string;
version?: string;
// ... other fields
};
retryable?: boolean; // Whether the error is retryable
}常见错误代码
INVALID_INPUT：输入参数无效（不可重试）TOPIC_NOT_FOUND：请求的主题不存在（不可重试）SECTION_NOT_FOUND：请求的节不存在（不可重试）VERSION_NOT_FOUND：请求的版本不存在（不可重试）NETWORK_ERROR：网络/HTTP错误（通常可重试）CACHE_ERROR：缓存操作失败（通常可重试）PROVIDER_ERROR：提供程序特定错误（不可重试）INTERNAL_ERROR：意外的内部错误（不可重试）
故障排除
服务器无法启动：
- 验证Node.js版本：
node --version（必须为18+） - 检查依赖关系：
npm install - 验证TypeScript编译：
npm run build - 检查日志中的特定错误消息
工具返回错误：
- 验证网络连接（针对在线提供商）
- 检查主题ID是否正确
- 验证文档版本是否存在
- 检查服务器日志以获取详细的错误信息
缓存不工作：
- 验证
SYNERGYDE_CACHE_DIR可写 - 检查缓存目录上的文件权限
- 在服务器日志中查找缓存错误
游标集成问题：
- 验证MCP配置文件语法（有效的JSON）
- 为服务器可执行文件使用绝对路径
- 检查Cursor的MCP服务器状态/日志
- 配置更改后重新启动Cursor
- 验证环境变量是否设置正确
发展
项目结构
src/
├── server.ts # Main MCP server entry point
├── types.ts # TypeScript type definitions
├── config.ts # Configuration and environment variables
├── tools/ # MCP tool implementations
│ ├── search-docs.ts
│ ├── get-topic.ts
│ ├── get-related-topics.ts
│ ├── list-section-topics.ts
│ └── describe-docs.ts
├── resources/ # MCP resource handlers
│ ├── topic-resource.ts
│ └── section-resource.ts
└── lib/
├── providers/ # Documentation providers (online/local/hybrid)
├── parser/ # HTML parsing and chunking
├── search/ # Search index implementation
├── cache/ # Disk caching layer
└── utils/ # Utilities (logger, errors)开发命令
# Build TypeScript
npm run build
# Watch mode for development
npm run dev
# Run linter
npm run lint
# Fix linting issues automatically
npm run lint:fix
# Type checking (no emit)
npm run typecheck
# Run tests
npm test
# Run tests with coverage
npm test -- --coverage
# Run tests in watch mode
npm run test:watch测试
该项目使用Vitest进行全面覆盖的测试：
- 单元测试：单独测试单个模块
- 集成测试：测试工具处理程序和工作流
- 端到端测试：测试完整流程（搜索→ get_topic→ 获取相关信息）
看 MANUAL_TESTING.md 用于手动测试程序。
代码质量
- TypeScript：已启用严格类型检查
- 埃斯林特：支持TypeScript的代码linting
- 测试覆盖率：要求报表覆盖率≥80%
- 错误处理：结构化错误负载，无未处理的异常
建筑
设计原则
- 模块化：具有明确职责的小型可组合模块
- 类型安全：贯穿始终的强TypeScript类型
- 错误处理：结构化错误，无未处理的异常
- 缓存：积极缓存以最大限度地减少网络调用
- 只读的：无写操作，尊重远程资源
- LLM友好：针对人工智能消费优化的分块、结构化内容
- 确定性的：经营稳健，业绩稳定
关键组件
- 提供商：从在线或本地来源获取文档
- 解析器：从HTML中提取和构造内容
- Chunker：将内容拆分为LLM友好的块
- 缓存：基于磁盘的解析主题缓存
- 搜索索引：具有相关性评分的内存全文搜索
- MCP服务器：通过模型上下文协议公开工具和资源
许可证
麻省理工学院
贡献
欢迎投稿！请确保：
- 所有测试均通过：
npm test - 代码键入正确（否
any类型） - 覆盖率保持≥80%
- Linting传球：
npm run lint