wso2-docs-mcp-server

WSO2 文档 MCP 服务

"这是一个非官方的社区项目，与 WSO2 无关联，也未获得 WSO2 认可。"

一款可用于生产环境的 Model Context Protocol（MCP） 服务，可通过检索增强生成（RAG），为 AI 助手（Claude Desktop、Claude Code、Cursor、VS Code）提供 WSO2 文档的语义搜索功能。

在底层，它采用高速双通道数据摄取引擎：

• **原生 GitHub：**通过 Git Trees API，直接从 WSO2 的公开 GitHub 仓库获取原始 Markdown（避免网页抓取带来的噪声和速率限制）
• **网页爬取备用方案：**适用于没有专用 GitHub 文档仓库的产品（例如 WSO2 Library）

架构

文档来源

产品	ID	URL
API Manager	apim	https://apim.docs.wso2.com
Micro Integrator	mi	https://mi.docs.wso2.com/en/4.4.0
Ballerina Integrator	bi	https://bi.docs.wso2.com
Choreo	choreo	https://wso2.com/choreo/docs
Identity Server	is	https://is.docs.wso2.com/en/latest
Ballerina	ballerina	https://ballerina.io/learn
WSO2 Library	library	https://wso2.com/library

前提条件

• Node.js ≥ 20
• Docker（用于 pgvector）
• 嵌入模型——默认无需 API 密钥：
  • Ollama（推荐）——在本地运行，首次运行时自动下载模型
  • 如果 Ollama 未运行，服务会自动回退到 HuggingFace ONNX（进程内运行，也会自动下载）
  • 也支持云服务提供商：OpenAI、Google Gemini、Voyage AI

---

快速开始

选择适合你使用场景的配置方式：

• 从 npm 安装——最简单，无需克隆
• 克隆并构建——适用于开发或贡献

---

从 npm 安装

全局安装此软件包，即可在系统范围内使用 wso2-docs-mcp-server、wso2-docs-crawl 和 wso2-docs-migrate 命令：

npm install -g wso2-docs-mcp-server

不想全局安装？ 以下每个步骤都可以使用 npx wso2-docs-mcp-server、npx wso2-docs-crawl 和 npx wso2-docs-migrate——只需将裸命令替换为对应的 npx 命令即可。

1. 启动 pgvector

下载 docker-compose.yml 并启动数据库：

curl -O https://raw.githubusercontent.com/iamvirul/wso2-docs-mcp-server/main/docker-compose.yml
docker compose up -d

2. 启动 Ollama（可选，但推荐）

安装 Ollama 并拉取默认嵌入模型：

ollama pull nomic-embed-text
ollama serve

没有 Ollama？ 跳过此步骤。服务会自动回退到 HuggingFace ONNX——模型会在首次使用时下载，无需额外配置。

3. 运行数据库迁移

DATABASE_URL="postgresql://wso2mcp:wso2mcp@localhost:5432/wso2docs" \
  wso2-docs-migrate

每当更改 EMBEDDING_DIMENSIONS（即切换嵌入服务提供商）时，都要再次运行迁移。脚本会自动检测并处理维度变更。

4. 为 WSO2 文档编制索引

# Index all products (first run downloads the embedding model automatically)
DATABASE_URL="postgresql://wso2mcp:wso2mcp@localhost:5432/wso2docs" \
  wso2-docs-crawl

# Index a single product (faster, great for testing)
DATABASE_URL="postgresql://wso2mcp:wso2mcp@localhost:5432/wso2docs" \
  wso2-docs-crawl --product ballerina --limit 20

# Force re-index even unchanged pages
DATABASE_URL="postgresql://wso2mcp:wso2mcp@localhost:5432/wso2docs" \
  wso2-docs-crawl --force

可用的产品 ID：apim、mi、bi、choreo、is、ballerina、library

5. 配置 AI 客户端

MCP 服务由 AI 客户端按需启动——无需后台进程。

Claude Desktop——编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "wso2-docs": {
      "command": "wso2-docs-mcp-server",
      "env": {
        "DATABASE_URL": "postgresql://wso2mcp:wso2mcp@localhost:5432/wso2docs",
        "EMBEDDING_PROVIDER": "ollama"
      }
    }
  }
}

Claude Code——在终端中运行一次：

claude mcp add wso2-docs \
  --transport stdio \
  -e DATABASE_URL="postgresql://wso2mcp:wso2mcp@localhost:5432/wso2docs" \
  -e EMBEDDING_PROVIDER="ollama" \
  -- wso2-docs-mcp-server

# Verify
claude mcp list

Cursor——在项目根目录中创建 .cursor/mcp.json：

{
  "mcpServers": {
    "wso2-docs": {
      "command": "wso2-docs-mcp-server",
      "env": {
        "DATABASE_URL": "postgresql://wso2mcp:wso2mcp@localhost:5432/wso2docs",
        "EMBEDDING_PROVIDER": "ollama"
      }
    }
  }
}

VS Code——创建 .vscode/mcp.json：

{
  "servers": {
    "wso2-docs": {
      "type": "stdio",
      "command": "wso2-docs-mcp-server",
      "env": {
        "DATABASE_URL": "postgresql://wso2mcp:wso2mcp@localhost:5432/wso2docs",
        "EMBEDDING_PROVIDER": "ollama"
      }
    }
  }
}

使用 npx 而非全局安装？ 将 "command": "wso2-docs-mcp-server" 替换为 "command": "npx"，并添加 "args": ["-y", "wso2-docs-mcp-server"]。

使用云嵌入服务提供商？ 将密钥添加到 env 中，例如 "EMBEDDING_PROVIDER": "openai", "OPENAI_API_KEY": "sk-..."。

---

克隆并构建

1. 克隆并安装

git clone https://github.com/iamvirul/wso2-docs-mcp-server.git
cd wso2-docs-mcp-server
npm install

2. 启动 Ollama（可选，但推荐）

安装 Ollama 并启动：

ollama serve

没有 Ollama？ 跳过此步骤。服务会检测到 Ollama 未运行，并自动回退到 HuggingFace ONNX 推理；模型会在首次使用时下载，无需额外设置。

3. 配置环境

cp .env.example .env
# Defaults work out of the box with Ollama.
# Only edit if using a cloud provider (OpenAI / Gemini / Voyage).

4. 启动 pgvector

docker compose up -d
# pgAdmin available at http://localhost:5050 ([email protected] / admin)

5. 运行数据库迁移

npm run db:migrate

注意： 每当更改 EMBEDDING_DIMENSIONS（即切换嵌入提供方）时，都要再次运行迁移。脚本会自动检测并处理维度变化。

6. 为文档建立索引

# Index all products
# On first run the embedding model is downloaded automatically (Ollama or HuggingFace)
npm run crawl

# Index a single product (faster, great for testing)
npm run crawl -- --product ballerina --limit 20

# Force re-index even unchanged pages
npm run crawl -- --force

7. 构建并启动 MCP 服务

npm run build
npm start

开发时（无需构建）：

npm run dev

8. 配置 AI 客户端

将 /ABSOLUTE/PATH/TO/wso2-docs-mcp-server 替换为实际的克隆路径。

Claude Desktop - 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "wso2-docs": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/wso2-docs-mcp-server/dist/src/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://wso2mcp:wso2mcp@localhost:5432/wso2docs",
        "EMBEDDING_PROVIDER": "ollama"
      }
    }
  }
}

Claude Code：

claude mcp add wso2-docs \
  --transport stdio \
  -e DATABASE_URL="postgresql://wso2mcp:wso2mcp@localhost:5432/wso2docs" \
  -e EMBEDDING_PROVIDER="ollama" \
  -- node "/ABSOLUTE/PATH/TO/wso2-docs-mcp-server/dist/src/index.js"

# Verify
claude mcp list

便捷脚本请参阅 config-examples/claude_code.sh。

Cursor - 创建 .cursor/mcp.json - 请参阅 config-examples/cursor_mcp.json。

VS Code - 创建 .vscode/mcp.json - 请参阅 config-examples/vscode_mcp.json。

---

MCP 工具

工具	描述
search_wso2_docs	对所有产品进行语义搜索。可选的 product 和 limit 筛选条件。
get_wso2_guide	在特定产品中搜索（apim、mi、bi、choreo、is、ballerina、library）。
explain_wso2_concept	在所有产品中广泛搜索概念，并返回排名前 8 的结果。
list_wso2_products	返回所有受支持产品的 ID 和基础 URL。

响应示例

[
  {
    "title": "Deploying WSO2 API Manager",
    "snippet": "WSO2 API Manager can be deployed in various topologies…",
    "source_url": "https://apim.docs.wso2.com/en/latest/install-and-setup/...",
    "product": "apim",
    "section": "Deployment Patterns",
    "score": 0.8712
  }
]

---

本地嵌入

默认的 EMBEDDING_PROVIDER=ollama 完全在你的机器上运行，无需 API 密钥。启动顺序如下：

Is Ollama running?
├── Yes → Is model present?
│         ├── Yes → Ready (instant)
│         └── No  → Pull via Ollama (streamed, runs once)
└── No  → Download ONNX model from HuggingFace Hub (~250 MB, cached after first run)
           and run inference in-process via @huggingface/transformers

默认情况下，这两种方式都使用 nomic-embed-text / Xenova/nomic-embed-text-v1，并生成完全相同的 768 维向量，因此可以在两者之间切换而无需重新建立索引。

硬件加速（HuggingFace ONNX 回退）

Ollama 不可用时，服务会自动检测最佳计算后端：

机器	检测方式	ONNX 数据类型	批次大小	吞吐量
Apple Silicon（M1/M2/M3/M4）	process.arch === 'arm64'	q8 INT8	32	约 9 毫秒/块
NVIDIA GPU	nvidia-smi 探测	fp32	64	取决于 GPU
其他所有设备	回退	q8 INT8	16	约 10 毫秒/块

为什么 Apple Silicon 使用 q8，而不是 CoreML/Metal？ CoreML 首次使用时会编译 Metal 着色器（冷启动约需 20 分钟）。对于此服务生成的典型块大小（每页 6–20 块），CPU↔GPU 传输开销会抵消任何推理性能提升。在 ARM NEON SIMD 上使用 INT8 量化推理，速度始终比 fp32 CPU 快约 100 倍，且没有冷启动开销。

基准测试（Apple M 芯片，Xenova/nomic-embed-text-v1）：

fp32 CPU (before): ~1,000 ms/chunk   (68 chunks ≈ 68 s of embedding)
q8  ARM NEON:          ~9 ms/chunk   (68 chunks ≈  0.6 s of embedding)  ← ~100× speedup

注意： 对于小规模抓取（≤ 10 页），总耗时主要取决于网络 I/O （从文档站点通过 HTTPS 获取内容），因此端到端性能提升有限。规模扩大后，嵌入速度提升会变得显著——抓取 500 页以上时，嵌入此前会耗费数小时。要获得最佳抓取性能，请运行 Ollama（ollama serve），它可原生并行处理推理，且没有每块开销。

---

环境变量

核心

变量	默认值	描述
DATABASE_URL	-	PostgreSQL 连接字符串（必需）
EMBEDDING_PROVIDER	ollama	ollama | openai | gemini | voyage
EMBEDDING_DIMENSIONS	768	必须与模型输出维度一致
CRAWL_CONCURRENCY	5	抓取期间的并发 HTTP 请求数
CHUNK_SIZE	800	每块的大致 Token 数
CHUNK_OVERLAP	100	块之间重叠的 Token 数
CACHE_TTL_SECONDS	3600	内存查询缓存 TTL
TOP_K_RESULTS	10	默认搜索结果数

Ollama（默认）

变量	默认值	描述
OLLAMA_BASE_URL	http://localhost:11434	Ollama 服务 URL
OLLAMA_EMBEDDING_MODEL	nomic-embed-text	通过 Ollama 拉取并使用的模型
HUGGINGFACE_EMBEDDING_MODEL	Xenova/nomic-embed-text-v1	Ollama 未运行时使用的 ONNX 回退模型

云服务提供商

变量	默认值	描述
OPENAI_API_KEY	-	当 EMBEDDING_PROVIDER=openai 时必需
OPENAI_EMBEDDING_MODEL	text-embedding-3-small	OpenAI 模型
GEMINI_API_KEY	-	当 EMBEDDING_PROVIDER=gemini 时必需
GEMINI_EMBEDDING_MODEL	text-embedding-004	Gemini 模型
VOYAGE_API_KEY	-	当 EMBEDDING_PROVIDER=voyage 时必需
VOYAGE_EMBEDDING_MODEL	voyage-3	Voyage 模型

嵌入维度参考

提供商	模型	维度
Ollama / HuggingFace	nomic-embed-text / Xenova/nomic-embed-text-v1	768（默认）
Ollama / HuggingFace	mxbai-embed-large / Xenova/mxbai-embed-large-v1	1024
Ollama / HuggingFace	all-minilm / Xenova/all-MiniLM-L6-v2	384
OpenAI	text-embedding-3-small	1536
OpenAI	text-embedding-3-large	3072
Gemini	text-embedding-004	768
Voyage	voyage-3	1024
Voyage	voyage-3-lite	512

---

定时重新索引

# Run a one-off re-index (checks hashes, skips unchanged pages)
npm run reindex

# Or from the project directory using node-cron (runs daily at 2 AM)
DATABASE_URL=... node -e "
  const { ReindexJob } = require('./dist/jobs/reindexDocs');
  const job = new ReindexJob();
  job.initialize().then(() => job.scheduleDaily());
"

---

项目结构

src/
  config/          env.ts · constants.ts
  vectorstore/     pgvector.ts · schema.sql
  ingestion/       crawler.ts · parser.ts · githubFetcher.ts · markdownParser.ts · chunker.ts · embedder.ts
  server/          mcpServer.ts · toolRegistry.ts
  jobs/            reindexDocs.ts
  index.ts
scripts/
  crawl.ts         CLI ingestion pipeline
  migrate.ts       Dynamic schema migration
config-examples/   claude_desktop.json · claude_code.sh · cursor_mcp.json · vscode_mcp.json
docker-compose.yml
.env.example

---

开发

# Type-check
npx tsc --noEmit

# Run crawl with tsx (no build needed)
npm run crawl -- --product ballerina --limit 5

# Run server in dev mode
npm run dev