Docusaurus MCP Server

Docusaurus MCP服务器

一个用于Docusaurus文档管理的综合模型上下文协议（MCP）服务器，使用TypeScript和MCP SDK构建。此服务器提供与Python MCP Docusaurus应用程序相同的功能。

特性

此服务器提供全面的文档管理功能，包括：

• 文档管理：创建、阅读、更新和继续编写文档
• 矢量搜索：使用嵌入在文档中进行语义搜索
• 网站地图生成：文档结构的层次视图
• 样式转换：将各种格式样式应用于内容
• 健康监测：服务健康检查和指标
• 文档跟踪不完整：跟踪和管理未完成的文档

可用工具

文档管理

• create_document -创建带有标题和内容的新文档条目
• update_docs -更新现有文档中的特定行
• continue_docs -将内容附加到文档并删除不完整的标记
• get_docs -按路径检索文档内容
• unfinished_docs -列出所有标记为不完整的文件

搜索与发现

• search_docs -跨文档嵌入执行语义搜索
• get_sitemap -生成文档结构的层次视图

内容转换

• apply_style -将样式转换应用于markdown内容
• get_styles -列出可用的样式转换

系统管理

• health_check -检查服务运行状况和状态
• metrics -获取服务指标（正常运行时间、请求、文档计数）
• sync_docs -将文档目录中的所有文档同步到矢量存储

安装

npm install

配置

环境变量

• DOCS_DIR -Docusaurus文档目录的路径（默认： ../aismarttalk-docs/docs)
• OPENAI_API_KEY -用于嵌入的OpenAI API密钥（可选，返回到简单的文本功能）

建筑

npm run build

运行服务器

选项1:标准传输

对于命令行集成和测试：

npm run stdio

这将使用stdin/stdout启动服务器进行通信，适用于：

• 命令行MCP客户端
• 开发和测试
• 与支持stdio的工具集成

选项2：无状态HTTP传输

对于基于web的集成：

npm run http

这将使用以下命令启动端口3000（或port环境变量）上的服务器：

• RESTful HTTP端点位于 /mcp
• 健康检查在 /health
• 服务器信息位于 /
• 浏览器客户端已启用CORS
• 无会话管理（无状态）

嵌入

服务器支持两种嵌入方法：

1. OpenAI嵌入 （推荐）：

- 集 OPENAI_API_KEY 环境变量 - 用途 text-embedding-ada-002 模型 - 高质量语义搜索

1. 简单文本功能 （回退）：

- 当OpenAI API密钥不可用时使用 - 基本词频和位置特征 - 仍然提供合理的搜索功能

可用的样式转换

• bold_headers -将所有标题加粗
• add_spacing -在线条之间添加额外的间距
• remove_comments -从内容中删除HTML注释
• clean_whitespace -清理尾随空格并规范换行
• add_toc -生成并添加目录
• format_code_blocks -清理代码块格式
• highlight_notes -突出显示注释/警告/重要部分

发展

# Build and run
npm run dev

建筑

服务器的结构如下：

• src/server.ts -使用所有工具实现核心服务器
• src/types.ts -TypeScript类型定义
• src/embeddings.ts -嵌入生成（OpenAI+回退）
• src/vector-store.ts -内存向量存储和搜索
• src/document-manager.ts -文件系统操作和文档管理
• src/sitemap.ts -文档结构生成
• src/styles.ts -内容样式转换
• src/metrics.ts -健康监测和指标
• src/stdio.ts -stdio传输实施
• src/http.ts -无状态HTTP传输实现
• src/index.ts -主要入境点和出口

运输详细信息

stdio运输

• 使用标准输入/输出进行通信
• 适用于CLI工具和直接集成
• 无网络依赖关系

无状态HTTP传输

• 每个请求都会创建一个新的服务器实例
• 请求之间没有保持会话状态
• 适用于水平可扩展的部署
• 浏览器客户端已启用CORS

测试

使用Makefile

该项目包括一个用于测试HTTP服务器的全面Makefile。

需求: curl, jq，以及bash shell。

备注：MCP服务器使用服务器发送事件（SSE）格式进行响应，这需要一个自动生成的特殊解析器脚本。

# See all available commands
make help

# Build and start server for testing
make build
make start-http

# Run all tests
make test-all

# Test individual endpoints
make test-info          # Test GET / endpoint
make test-health        # Test GET /health endpoint  
make test-mcp-init      # Test MCP initialization
make test-list-tools    # Test listing tools
make test-search-docs   # Test document search
make test-create-doc    # Test document creation
make test-get-sitemap   # Test sitemap generation
make test-health-check  # Test health check tool
make test-metrics       # Test metrics tool

# Test error handling
make test-error-handling
make test-invalid-methods

# Run a proper MCP client sequence
make test-sequence

# Performance testing
make test-performance

# Clean up
make stop-server
make clean

快速演示

有关所有功能的完整演示：

./demo.sh

此脚本将构建项目、启动服务器、运行各种测试并自动清理。

手动测试

您还可以使用 MCP检查员 或者通过实现简单的MCP客户端。

示例用法

文档管理工作流程

1. 创建新文档:

   {
     "tool": "create_document",
     "arguments": {
       "path": "api/new-endpoint.md",
       "title": "New API Endpoint",
       "content": "This endpoint provides...",
       "mark_incomplete": true
     }
   }

1. 搜索相关内容:

   {
     "tool": "search_docs",
     "arguments": {
       "query": "API authentication methods",
       "top_k": 5
     }
   }

1. 继续编写文档:

   {
     "tool": "continue_docs",
     "arguments": {
       "path": "api/new-endpoint.md",
       "continuation": "## Authentication\n\nThis endpoint requires..."
     }
   }

1. 应用样式转换:

   {
     "tool": "apply_style",
     "arguments": {
       "style_id": "add_toc",
       "content": "# My Document\n\n## Section 1..."
     }
   }

HTTP端点

运行HTTP服务器时：

• GET / -服务器信息
• GET /health -健康检查
• POST /mcp -MCP协议端点
• GET /mcp -返回405（在无状态模式下不支持）
• DELETE /mcp -返回405（在无状态模式下不支持）

与Python版本的比较

此TypeScript实现提供了与Python MCP Docusaurus应用程序相同的功能：

许可证

麻省理工学院