使用说明

WSO2文档MCP服务器

“这是一个非官方的社区项目。不隶属于WSO2或得到WSO2的认可。”

生产准备就绪 模型上下文协议（MCP） 该服务器通过检索增强生成（RAG）为AI助手（Claude Desktop、Claude Code、Cursor、VS Code）提供WSO2文档的语义搜索。

在引擎盖下，它使用了一个超快的双摄入引擎：

GitHub原生： 通过Git Trees API直接从WSO2的公共GitHub存储库获取原始Markdown（避免网络抓取噪音和速率限制）
Web爬网回退： 对于没有专用GitHub文档仓库的产品（如WSO2库）

建筑

文档来源

产品	ID	URL
API经理	`apim`	https://apim.docs.wso2.com
微型集成器	`mi`	https://mi.docs.wso2.com/en/4.4.0
Ballerina集成商	`bi`	https://bi.docs.wso2.com
合唱	`choreo`	https://wso2.com/choreo/docs
身份服务器	`is`	https://is.docs.wso2.com/en/latest
芭蕾舞演员	`ballerina`	https://ballerina.io/learn
WSO2库	`library`	https://wso2.com/library

先决条件

Node.js ≥ 20
码头工人 （适用于pgvector）
嵌入 -默认情况下不需要API密钥：
- 奥拉玛 （推荐）-在本地运行，首次运行时自动下载模型
- 如果Ollama未运行，服务器将自动回退到 拥抱面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

没有奥拉玛？ 跳过此步骤。服务器在首次使用时自动回退到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客户端按需启动，无需后台进程。

克劳德桌面 -编辑 ~/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 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/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未运行，并自动回退到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 (admin@wso2mcp.local / 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 使用您的实际克隆路径。

克劳德桌面 -编辑 ~/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 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/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个dim向量，因此您可以在它们之间切换而无需重新索引。

硬件加速（HuggingFace ONNX回退）

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

机器	检测	ONNX数据类型	批量大小	吞吐量
苹果硅（M1/M2/M3/M4）	`process.arch === 'arm64'`	`q8` INT8	32	~9毫秒/块
英伟达GPU	`nvidia-smi` 探头	`fp32`	64	取决于GPU
所有其他	回退	`q8` INT8	16	~10ms/块

为什么 q8 用苹果硅代替CoreML/Metal？ CoreML在首次使用时编译金属着色器（冷启动约20分钟）。对于该服务器产生的典型块大小（每页6-20个块），CPU↔GPU传输开销消除了任何推理增益。基于ARM NEON SIMD的INT8量化推理是一致的 比fp32 CPU快约100倍 冷启动成本为零。

Benchmark（苹果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`
`EMBEDDING_DIMENSIONS`	`768`	必须与模型输出尺寸匹配
`CRAWL_CONCURRENCY`	`5`	爬网期间并发HTTP请求
`CHUNK_SIZE`	`800`	每个区块的近似令牌
`CHUNK_OVERLAP`	`100`	块之间的重叠标记
`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`	航行模型

嵌入尺寸参考

供应商	型号	尺寸
奥利玛/拥抱脸	`nomic-embed-text` / `Xenova/nomic-embed-text-v1`	768 （默认）
奥利玛/拥抱脸	`mxbai-embed-large` / `Xenova/mxbai-embed-large-v1`	1024
奥利玛/拥抱脸	`all-minilm` / `Xenova/all-MiniLM-L6-v2`	384
OpenAI	`text-embedding-3-small`	1536
OpenAI	`text-embedding-3-large`	3072
双子座	`text-embedding-004`	768
航行	`voyage-3`	1024
航行	`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

使用说明

WSO2文档MCP服务器

建筑

文档来源

先决条件

快速开始

从npm安装

1.启动pgvector

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

3.运行数据库迁移

4.WSO2文件索引

5.配置您的AI客户端

克隆和构建

1.克隆并安装

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

3.配置环境

4.启动pgvector

5.运行数据库迁移

6.索引文件

7.构建并启动MCP服务器

8.配置您的AI客户端

MCP工具

示例响应

本地嵌入

硬件加速（HuggingFace ONNX回退）

环境变量

核心

Ollama（默认）

云提供商

嵌入尺寸参考

计划重新索引

项目结构

发展

相关 MCP

AI持久记忆服务器

DuckDuckGo 搜索 MCP 服务器

图表生成MCP服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

AI开发助手