cangjie-mcp 0.1.0

MCP server for Cangjie programming language documentation

Cangjie MCP Server

仓颉编程语言文档的 MCP (Model Context Protocol) 服务器，提供基于 RAG (Retrieval-Augmented Generation) 的智能文档搜索功能。

功能特性

• 基于向量检索的语义搜索
• 支持本地嵌入模型和 OpenAI 嵌入模型
• 支持本地 Rerank 和 SiliconFlow Rerank 提升搜索质量
• 自动下载和索引仓颉官方文档
• 支持预构建索引的创建和下载
• 完整的 MCP 协议支持

安装

# 使用 pip 安装
pip install cangjie-mcp

# 或使用 uv 安装
uv pip install cangjie-mcp

快速开始

# 启动 MCP 服务器（使用默认配置）
cangjie-mcp serve

# 使用本地 rerank 提升搜索质量
cangjie-mcp serve --rerank local

# 指定文档版本和语言
cangjie-mcp serve --version v1.0.4 --lang zh

命令

serve - 启动 MCP 服务器

启动 MCP 服务器，自动初始化文档仓库并构建索引（如果需要）。

cangjie-mcp serve [OPTIONS]

选项：

选项	简写	类型	默认值	说明
--version	-v	TEXT	latest	文档版本（git tag）
--lang	-l	TEXT	zh	文档语言（zh/en）
--embedding	-e	TEXT	local	嵌入类型（local/openai）
--local-model		TEXT	paraphrase-multilingual-MiniLM-L12-v2	本地 HuggingFace 嵌入模型名称
--openai-api-key		TEXT		OpenAI API 密钥
--openai-base-url		TEXT	https://api.openai.com/v1	OpenAI API 基础 URL
--openai-model		TEXT	text-embedding-3-small	OpenAI 嵌入模型
--rerank	-r	TEXT	none	Rerank 类型（none/local/siliconflow）
--rerank-model		TEXT	BAAI/bge-reranker-v2-m3	Rerank 模型名称（用于本地 rerank）
--rerank-top-k		INTEGER	5	Rerank 后返回的结果数量
--rerank-initial-k		INTEGER	20	Rerank 前检索的候选数量
--siliconflow-api-key		TEXT		SiliconFlow API 密钥
--siliconflow-base-url		TEXT	https://api.siliconflow.cn/v1	SiliconFlow API 基础 URL
--siliconflow-rerank-model		TEXT	BAAI/bge-reranker-v2-m3	SiliconFlow Rerank 模型
--data-dir	-d	PATH	~/.cangjie-mcp	数据目录路径
--transport	-t	TEXT	stdio	传输类型（stdio/http）
--port	-p	INTEGER	8000	HTTP 端口（仅用于 http 传输）

示例：

# 使用本地嵌入和本地 rerank
cangjie-mcp serve --embedding local --rerank local

# 使用 OpenAI 嵌入
cangjie-mcp serve --embedding openai --openai-api-key sk-xxx

# 使用 SiliconFlow rerank
cangjie-mcp serve --rerank siliconflow --siliconflow-api-key sk-xxx

# 使用 HTTP 传输
cangjie-mcp serve --transport http --port 8080

prebuilt build - 构建预构建索引

构建预构建索引归档文件，包含向量数据库和元数据。

cangjie-mcp prebuilt build [OPTIONS]

选项：

选项	简写	类型	默认值	说明
--version	-v	TEXT	latest	文档版本（git tag）
--lang	-l	TEXT	zh	文档语言（zh/en）
--embedding	-e	TEXT	local	嵌入类型（local/openai）
--embedding-model	-m	TEXT		嵌入模型名称
--data-dir	-d	PATH	~/.cangjie-mcp	数据目录
--output	-o	PATH		输出目录或文件路径

示例：

# 构建默认版本的预构建索引
cangjie-mcp prebuilt build

# 构建指定版本的索引
cangjie-mcp prebuilt build --version v0.53.18 --lang zh

# 指定输出路径
cangjie-mcp prebuilt build --output ./my-index.tar.gz

prebuilt download - 下载预构建索引

从指定 URL 下载预构建索引。

cangjie-mcp prebuilt download [OPTIONS]

选项：

选项	简写	类型	默认值	说明
--url	-u	TEXT		下载 URL
--version	-v	TEXT	latest	要下载的版本
--lang	-l	TEXT	zh	要下载的语言

示例：

# 从指定 URL 下载
cangjie-mcp prebuilt download --url https://example.com/index.tar.gz

# 使用环境变量配置的 URL
export CANGJIE_PREBUILT_URL=https://example.com/index.tar.gz
cangjie-mcp prebuilt download

prebuilt list - 列出预构建索引

列出本地可用的预构建索引。

cangjie-mcp prebuilt list

环境变量配置

所有配置都可以通过环境变量设置，支持 .env 文件。

文档配置

环境变量	默认值	说明
CANGJIE_DOCS_VERSION	latest	文档版本（git tag）
CANGJIE_DOCS_LANG	zh	文档语言（zh/en）
CANGJIE_DATA_DIR	~/.cangjie-mcp	数据目录路径
CANGJIE_PREBUILT_URL		预构建索引下载 URL

嵌入配置

环境变量	默认值	说明
CANGJIE_EMBEDDING_TYPE	local	嵌入类型（local/openai）
CANGJIE_LOCAL_MODEL	paraphrase-multilingual-MiniLM-L12-v2	本地 HuggingFace 嵌入模型
OPENAI_API_KEY		OpenAI API 密钥
OPENAI_BASE_URL	https://api.openai.com/v1	OpenAI API 基础 URL
OPENAI_MODEL	text-embedding-3-small	OpenAI 嵌入模型

Rerank 配置

环境变量	默认值	说明
CANGJIE_RERANK_TYPE	none	Rerank 类型（none/local/siliconflow）
CANGJIE_RERANK_LOCAL_MODEL	BAAI/bge-reranker-v2-m3	本地 Rerank 模型
CANGJIE_RERANK_TOP_K	5	Rerank 后返回的结果数量
CANGJIE_RERANK_INITIAL_K	20	Rerank 前检索的候选数量
SILICONFLOW_API_KEY		SiliconFlow API 密钥
SILICONFLOW_BASE_URL	https://api.siliconflow.cn/v1	SiliconFlow API 基础 URL
SILICONFLOW_RERANK_MODEL	BAAI/bge-reranker-v2-m3	SiliconFlow Rerank 模型

配置文件示例

创建 .env 文件：

# 文档配置
CANGJIE_DOCS_VERSION=v0.53.18
CANGJIE_DOCS_LANG=zh
CANGJIE_DATA_DIR=~/.cangjie-mcp

# 嵌入配置（使用本地模型）
CANGJIE_EMBEDDING_TYPE=local
CANGJIE_LOCAL_MODEL=paraphrase-multilingual-MiniLM-L12-v2

# 或使用 OpenAI 嵌入
# CANGJIE_EMBEDDING_TYPE=openai
# OPENAI_API_KEY=sk-your-api-key
# OPENAI_MODEL=text-embedding-3-small

# Rerank 配置（使用本地 rerank）
CANGJIE_RERANK_TYPE=local
CANGJIE_RERANK_LOCAL_MODEL=BAAI/bge-reranker-v2-m3
CANGJIE_RERANK_TOP_K=5
CANGJIE_RERANK_INITIAL_K=20

# 或使用 SiliconFlow rerank
# CANGJIE_RERANK_TYPE=siliconflow
# SILICONFLOW_API_KEY=sk-your-api-key

MCP 工具

服务器提供以下 MCP 工具：

工具名称	说明
search_docs	搜索文档，支持语义搜索和分类过滤
get_topic	获取指定主题的完整文档内容
list_topics	列出所有可用主题，支持按分类筛选
get_code_examples	获取代码示例，支持按语言过滤
get_tool_usage	获取工具使用说明（如 cjc、cjpm）

与 Claude Code 集成

方式一：命令行添加（推荐）

使用 claude mcp add 命令快速添加 MCP 服务器：

claude mcp add cangjie -- uvx cangjie-mcp serve

# 使用 uvx 运行并启用本地 rerank
claude mcp add cangjie -- uvx cangjie-mcp serve --rerank local

# 添加环境变量
claude mcp add -e CANGJIE_RERANK_TYPE=local cangjie -- uvx cangjie-mcp serve

# 使用已安装的 cangjie-mcp
claude mcp add cangjie -- cangjie-mcp serve --rerank local

常用 claude mcp 命令：

# 查看已配置的 MCP 服务器
claude mcp list

# 查看服务器详情
claude mcp get cangjie

# 移除服务器
claude mcp remove cangjie

方式二：配置文件

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "cangjie": {
      "command": "uvx",
      "args": ["cangjie-mcp", "serve", "--rerank", "local"]
    }
  }
}

或者使用已安装的命令：

{
  "mcpServers": {
    "cangjie": {
      "command": "cangjie-mcp",
      "args": ["serve", "--rerank", "local"]
    }
  }
}

开发

# 安装开发依赖
uv sync --all-extras

# 运行测试
uv run pytest

# 运行单元测试
uv run pytest tests/unit/

# 运行集成测试
uv run pytest tests/integration/

许可证

MIT License