使用说明

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
无会话管理（无状态）

嵌入

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

OpenAI嵌入 （推荐）：
- 集 OPENAI_API_KEY 环境变量
- 用途 text-embedding-ada-002 模型
- 高质量语义搜索
简单文本功能 （回退）：
- 当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客户端。

示例用法

文档管理工作流程

创建新文档:

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

搜索相关内容:

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

继续编写文档:

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

应用样式转换:

{
  "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应用程序相同的功能：

特性	Python版本	TypeScript版本
文档CRUD	✅ FastAPI+SQLAlchemy	✅ fs extra+矢量存储
矢量搜索	✅ PostgreSQL+pgvector	✅ 内存+余弦相似度
嵌入	✅ 句子变换器	✅ OpenAI API+回退
健康/指标	✅ FastAPI端点	✅ MCP工具
风格转换	✅ Python函数	✅ TypeScript函数
网站地图生成	✅ 文件系统遍历	✅ 文件系统遍历

许可证

麻省理工学院