Nats Docs MCP Server

NATS文档MCP服务器

一种模型上下文协议（MCP）服务器，为LLM提供对NATS文档的编程访问https://docs.nats.io/.可选地支持双文档源，包括Synadia Control Plane文档。

特性

• 符合MCP标准的服务器 公开文档搜索和检索工具
• 双重文件来源 -NATS文档（始终启用）和可选的Synadia控制平面文档
• 智能查询分类 -根据关键字自动将查询路由到适当的文档源
• 快速内存索引 TF-IDF相关性排名和每个来源的单独索引
• 基于会话的缓存 -文档在启动时提取一次，为会话缓存
• 优雅降级 -如果Syncp文档获取失败，服务器将仅继续使用NATS文档
• 单二进制分布 没有外部依赖关系
• 与跨平台支持 -Linux、macOS、AMD64和ARM64上的Windows
• 结构化日志记录 具有可配置的日志级别
• 平滑关闭 进行适当的资源清理

安装

下载预构建的二进制文件

从以下网址下载适用于您平台的最新版本 发布页面.

提取存档：

tar -xzf nats-docs-mcp-server_*.tar.gz
cd nats-docs-mcp-server_*

从源代码构建

要求：

• 转到1.22或更高版本
• GoRelease（用于建筑）

# Clone the repository
git clone https://github.com/j4ng5y/nats-docs-mcp-server.git
cd nats-docs-mcp-server

# Build with GoReleaser
goreleaser build --snapshot --clean

# Binary will be in dist/ directory
./dist/nats-docs-mcp-server_linux_amd64_v1/nats-docs-mcp-server --version

配置

服务器可以通过以下方式配置：

1. 命令行标志（最高优先级）
2. 配置文件（YAML）
3. 环境变量
4. 默认值（最低优先级）

配置文件

创建 config.yaml 文件（参见 config.example.yaml 完整示例）：

log_level: info
docs_url: https://docs.nats.io
fetch_timeout: 30s
max_retries: 3
retry_backoff: 1s
max_search_results: 10

命令行标志

nats-docs-mcp-server --config config.yaml --log-level debug

可用标志：

• --config -配置文件的路径
• --log-level -日志级别（调试、信息、警告、错误）
• --version -显示版本信息
• --help -显示帮助消息

环境变量

所有配置选项都可以通过环境变量进行设置 NATS_DOCS_ 前缀：

export NATS_DOCS_LOG_LEVEL=debug
export NATS_DOCS_DOCS_URL=https://docs.nats.io
export NATS_DOCS_FETCH_TIMEOUT=30s

缓存

服务器缓存获取的文档，以实现脱机操作和更快的启动。

缓存行为

• 首次运行：从网络获取文档，创建缓存（~5-30秒）
• 后续运行：从缓存加载（如果有效），速度极快（\<1秒）
• 自动刷新：如果缓存超过7天，则自动刷新（可配置）

缓存位置

违约： ~/.cache/nats-mcp/

通过环境变量进行覆盖：

export NATS_DOCS_CACHE_DIR=/custom/cache/path
export NATS_DOCS_CACHE_MAX_AGE_DAYS=30  # Default: 7 days

手动刷新

启动时刷新文档缓存：

./nats-docs-mcp-server --refresh-cache

或者使用 refresh_docs_cache 在运行时从LLM客户端刷新MCP工具。

离线模式

如果存在有效的缓存，服务器将完全脱机工作。创建初始缓存后不需要网络连接。

Syncp（Synadia控制平面）文档支持

服务器支持可选的双文档源：NATS和Synadia Control Plane。默认情况下，为了向后兼容，此功能被禁用。

启用同步支持

要启用Syncp文档支持，请将以下内容添加到您的 config.yaml:

syncp:
  enabled: true
  base_url: https://docs.synadia.com/control-plane
  fetch_timeout: 30s

classification:
  syncp_keywords:
    - syncp
    - control-plane
    - synadia
    - namespace
    - managed
  nats_keywords:
    - jetstream
    - nats-server
    - nats-cli
    - subject
    - stream
    - consumer

查询分类

启用Syncp后，查询会自动分类并路由到相应的文档源：

分类规则：

• 仅限NATS：查询仅包含NATS关键字（例如“jetstream”、“consumer”）
• 仅同步：查询仅包含Syncp关键字（例如，“控制平面”、“命名空间”）
• 两个来源：查询包含来自两个来源的关键字或没有特定的关键字
• 将两个来源的结果合并，并按相关性得分进行排名

故障弱化

如果Syncp文档获取在启动过程中失败：

• 服务器记录警告
• 仅使用NATS文档继续运行
• 对用户没有服务中断或错误
• 这确保了即使Syncp源暂时不可用，服务器也保持可用

向后兼容

• Syncp支持 默认情况下禁用 (syncp.enabled: false)
• 无需添加Syncp配置，现有配置即可保持不变
• 仅保留默认的NATS行为
• MCP工具界面无中断更改

用法

运行服务器

./nats-docs-mcp-server --config config.yaml

服务器使用MCP协议通过stdio进行通信。它旨在供MCP客户端（如Claude Desktop、IDE或其他AI助手）使用。

MCP工具

服务器公开了两个MCP工具：

1.搜索_nats_docs

按查询字符串搜索NATS文档。

参数：

• query （字符串，必填）-搜索查询
• limit （整数，可选）-最大结果数（默认值：10）

例子：

{
  "query": "jetstream consumer",
  "limit": 5
}

退货： 包含以下内容的搜索结果数组：

• title -文档标题
• url -文档URL
• source -启用双源时的文档源（“NATS”或“Syncp”）
• summary -带查询上下文的简短摘录
• relevance -相关性得分（0-1）

2.retrieve_nats.doc

检索特定文档页面的完整内容。

参数：

• doc_id （字符串，必填）-文档ID或URL路径

例子：

{
  "doc_id": "/nats-concepts/jetstream"
}

退货： 完整的文档包括：

• title -文档标题
• url -文档URL
• content -完整文档内容
• sections -章节标题数组

与Claude Desktop一起使用

添加到您的Claude Desktop MCP配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "nats-docs": {
      "command": "/path/to/nats-docs-mcp-server",
      "args": ["--config", "/path/to/config.yaml"]
    }
  }
}

运输类型

服务器支持不同部署场景的多种传输机制：

STDIO传输（默认）

默认传输使用标准输入/输出，非常适合基于本地流程的集成。

使用案例：

• 本地开发和测试
• Claude Desktop和其他本地MCP客户端
• 子流程管理I/O的嵌入式集成
• 客户端和服务器在同一台机器上运行的场景

配置：

通过命令行（使用默认值）：

./nats-docs-mcp-server --config config.yaml

通过环境变量：

export NATS_DOCS_TRANSPORT_TYPE=stdio
./nats-docs-mcp-server

通过配置文件：

transport_type: stdio

SSE传输（服务器发送事件）

基于HTTP的传输，使用服务器发送事件进行实时服务器到客户端通信。

使用案例：

• 基于Web的客户端
• 浏览器集成
• 远程部署
• 具有服务器事件的多客户端场景

配置：

通过命令行：

./nats-docs-mcp-server --transport sse --host localhost --port 8080

通过环境变量：

export NATS_DOCS_TRANSPORT_TYPE=sse
export NATS_DOCS_HOST=0.0.0.0
export NATS_DOCS_PORT=8080
./nats-docs-mcp-server

通过配置文件：

transport_type: sse
host: 0.0.0.0
port: 8080

流式HTTP传输

具有请求/响应和SSE支持的完整HTTP传输，适用于企业部署。

使用案例：

• 企业集成
• 完整的HTTP API要求
• 负载均衡部署
• 复杂的路由场景

配置：

通过命令行：

./nats-docs-mcp-server --transport streamablehttp --host 0.0.0.0 --port 8080

通过环境变量：

export NATS_DOCS_TRANSPORT_TYPE=streamablehttp
export NATS_DOCS_HOST=0.0.0.0
export NATS_DOCS_PORT=8080
./nats-docs-mcp-server

通过配置文件：

transport_type: streamablehttp
host: 0.0.0.0
port: 8080

建筑

组件

• 多源提取器 -HTTP客户端支持双文档源（NATS和Syncp），具有共享重试逻辑和速率限制
• 解析器 -HTML解析器从文档页面中提取结构化内容（源代码无关）
• 索引管理 -管理NATS和Syncp文档的单独内存TF-IDF搜索索引
• 分类器 -基于关键字的查询分类器将查询路由到适当的文档源
• 搜索编排器 -基于分类协调多源搜索并合并结果
• 服务器 -MCP服务器核心处理协议通信和工具调用
• 工具 -MCP工具处理程序，用于使用可选源元数据进行搜索和检索

缓存策略

服务器使用基于会话的内存缓存：

• 文档在服务器启动时提取一次
• 缓存在整个服务器会话中持续存在
• 缓存在会话之间不会持久化到磁盘
• 每次服务器重启都会获取新的文档
• 初始启动后无网络请求

优点：

• 始终保持最新文档（在启动时获取）
• 无过时数据问题（重启时缓存已清除）
• 快速响应时间（启动后无网络I/O）
• 可预测的内存使用量（~15-75 MB）

权衡：

• 启动时间包括文档获取（5-30秒）
• 启动时需要网络连接

发展

运行测试

# Run unit tests
go test -v ./...

# Run tests with coverage
go test -v -race -coverprofile=coverage.out ./...

# Run specific package tests
go test -v ./internal/index

# Run property-based tests (manual only, takes longer)
go test -v -tags=property ./...

注： 基于属性的测试位于构建标记之后，必须显式运行 -tags=property。它们不会在CI中自动运行，以加快构建时间。要在GitHub Actions中运行属性测试，请从Actions选项卡手动触发“基于属性的测试”工作流。

建筑

始终使用GoRelease进行构建：

# Development build
goreleaser build --snapshot --clean

# Test full release process locally
goreleaser release --snapshot --clean

项目结构

.
├── cmd/server/          # Main entry point
├── internal/
│   ├── classifier/      # Query classification (NATS/Syncp routing)
│   ├── config/          # Configuration management
│   ├── fetcher/         # Documentation fetching (dual-source support)
│   ├── parser/          # HTML parsing
│   ├── index/           # Search indexing and management
│   ├── search/          # Multi-source search orchestration
│   ├── logger/          # Structured logging
│   └── server/          # MCP server core
├── .github/workflows/   # CI/CD workflows
└── .goreleaser.yaml     # Build configuration

故障排除

服务器无法启动

问题： 服务器立即退出或显示连接错误。

解决方案：

• 检查是否没有其他进程正在使用stdio
• 验证配置文件是否为有效的YAML
• 检查日志输出是否存在特定错误

文档获取失败

问题： 服务器在启动过程中超时或发生故障。

解决方案：

• 验证网络连接到https://docs.nats.io
• 增加 fetch_timeout 在配置中
• 检查防火墙/代理设置

搜索未返回任何结果

问题： 搜索查询返回空结果。

解决方案：

• 验证文档是否已成功获取（检查日志）
• 尝试更广泛的搜索词
• 检查索引是否已构建（在日志中查找“已索引的N个文档”）

内存使用率高

问题： 服务器使用的内存比预期的多。

解决方案：

• 这是意料之中的——所有文档都缓存在内存中
• 典型用法：15-75MB，具体取决于文档大小
• 重新启动服务器以清除缓存并获取新文档

贡献

看 贡献.md 发展指南。

许可证

\[在此处添加您的许可证\]

致谢

• 建于 mcp走 -MCP SDK for Go
• 用途 zerolog 用于结构化日志记录
• 文档来源 NATS.io