Wso2 Docs MCP Server

WSO2文档MCP服务器

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

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

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

建筑

flowchart TD
    %% Styling
    classDef github fill:#1f2328,color:#fff,stroke:#e1e4e8
    classDef default fill:#0969da,color:#fff,stroke:#0969da
    classDef db fill:#218bff,color:#fff,stroke:#218bff
    classDef web fill:#0969da,color:#fff,stroke:#0969da

    subgraph Sources ["Information Sources"]
        GH["GitHub Repos\n(wso2/docs-apim, etc.)"]:::github
        Web["WSO2 Websites\n(ballerina.io, lib)"]:::web
    end

    subgraph Ingestion ["Dual-Ingestion Pipeline"]
        A["GitHubDocFetcher\n(Git Trees API)"] 
        B["DocCrawler\n(HTML scraping)"]
        
        C["MarkdownParser\n(Front-matter & Heads)"]
        D["DocParser\n(Cheerio HTML parsing)"]
        
        E["DocChunker\n(Semantic Splitting)"]
    end

    subgraph Embedding ["Vectorization & Storage"]
        F["EmbedderFactory\n(Ollama / HuggingFace)"]
        G[("pgvector\n(PostgreSQL)")]:::db
    end

    %% Flow
    GH --> A
    Web --> B
    
    A -->|"Raw .md"| C
    B -->|"Clean HTML"| D
    
    C -->|"ParsedSection[]"| E
    D -->|"ParsedSection[]"| E
    
    E -->|"Tokens/Chunks"| F
    F -->|"768-dim Vectors"| G

文档来源

先决条件

• Node.js ≥ 20
• 码头工人 （适用于pgvector）
• 嵌入 -默认情况下不需要API密钥：

- 奥拉玛 （推荐）--在本地运行，首次运行时自动下载模型 - 如果Ollama未运行，服务器将自动回退到 拥抱面ONNX （正在处理，也会自动下载） - 还支持云提供商：OpenAI、Google Gemini、Voyage AI

______________________________________________________________________

快速开始

选择适合您用例的设置路径：

• **** --最简单，无需克隆
• 克隆和构建 --发展或贡献

______________________________________________________________________

从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, choreo, ballerina, bi, 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代码 --创建 .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代码 --创建 .vscode/mcp.json --看 config-examples/vscode_mcp.json.

______________________________________________________________________

MCP工具

示例响应

[
  {
    "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不可用时，服务器会自动检测最佳计算后端：

为什么 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) 其原生地并行推理，并且没有每个块的开销。

______________________________________________________________________

环境变量

核心

Ollama（默认）

云提供商

嵌入尺寸参考

______________________________________________________________________

计划重新索引

# 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