Ant Design MCP Server (Python)

This Model Context Protocol (MCP) server fetches and structures Ant Design v4 (Chinese) component documentation into JSON so AI agents can perform analysis.

Features

Fetch overview page and individual component pages.
Extract component metadata: name, description, examples.
Classify API tables automatically (props / events / methods / other).
Cache fetched HTML locally.
Export all components into a single JSON file.
MCP tools exposed over JSON-RPC stdio.

Tools

list_components(force?)
get_component(name, force?)
search_components(query)
export_all(force?, filepath?)

Environment Setup

Choose one method (requirements are inside src/requirements.txt):

venv (built-in)

python -m venv .venv source .venv/bin/activate pip install -r src/requirements.txt

pyenv + venv

brew install pyenv pyenv install 3.11.8 pyenv local 3.11.8 python -m venv .venv source .venv/bin/activate pip install -r src/requirements.txt

Conda

conda create -n antd-mcp python=3.11 -y conda activate antd-mcp pip install -r src/requirements.txt

Run Server (Source Checkout)

Flat layout now exposes modules directly under src/:

python -m server # or explicit path python src/server.py

Console scripts (after install or via pipx):

# 使用管道输入 JSON-RPC 请求 echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | antd-mcp-server # 带格式化输出 echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | antd-mcp-server --color --pretty # 长会话模式（stdin 流式输入） antd-mcp-server

JSON-RPC Examples

# List tools echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python -m server # List components echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_components","arguments":{}}}' | python -m server # Get one component echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_component","arguments":{"name":"Button"}}}' | python -m server # Search components echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"search_components","arguments":{"query":"form"}}}' | python -m server # Export all component data echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"export_all","arguments":{}}}' | python -m server

Export Output

Default file: src/exports/antd_components_all.json Structure:

{ "generated_at": <timestamp>, "count": <number_of_components>, "components": [ { "name": "Button", "title": "Button 按钮", "intro": [...], "props": [...], "events": [...], "methods": [...], "other_tables": [...], "table_summary": {"props":1,"events":0,...}, "examples": [...], "source_url": "https://4x.ant.design/..." } ] }

TODO / Roadmap

More precise table classification rules (column semantics).
Parallel fetching & retry with backoff.
Version / language (en vs cn) selection.
CLI wrapper.
Optional rate limiting.

License

MIT (add if needed)

安装 (发布后)

pip install antd-mcp-server # 或使用 pipx 隔离运行 pipx install antd-mcp-server

安装后命令行入口：

然后向 stdin 逐行发送 JSON 请求。

本地构建与发布

# 构建 python -m build # 上传到 PyPI python -m twine upload dist/*

自动化脚本

提供 scripts/release.sh 简化发布流程：

# 正常发布新版本 0.1.1 ./scripts/release.sh 0.1.1 # 仅构建 + 校验 (不上传、不推送 tag) ./scripts/release.sh 0.1.1 --dry-run

依赖:

已安装 build 与 twine (pip install build twine)
已通过测试 (pytest -q)；脚本会先跑测试。
PyPI 凭证 (推荐 Token):
export TWINE_USERNAME="__token__" export TWINE_PASSWORD="pypi-xxxxx" # 在 PyPI 创建的 token

脚本步骤:

检查 git 工作区是否干净
运行测试
更新 pyproject.toml 中版本号
提交并打 tag v<version>
构建 (wheel + sdist)
twine check 验证
上传 (跳过若 dry-run)
推送 commit 与 tag

注意事项:

使用 sed 简单替换版本号行，保持现有格式。
若需要预发行版本，可传入 0.2.0rc1 等。
若需要撤销，可删除 tag 并重置 commit：git tag -d v0.1.1 && git reset --hard HEAD~1。

供 AI 工具使用的 mcp.json 示例

方式1：使用已安装的包（推荐）

首先安装包：

pipx install antd-mcp-server # 或从本地 wheel 安装 pipx install --force dist/antd_mcp_server-0.1.1-py2.py3-none-any.whl

然后配置 mcp.json：

{ "version": 1, "servers": { "antd_mcp": { "command": "antd-mcp-server", "args": [], "timeoutSeconds": 60 } } }

方式2：直接运行源码（开发模式）

如果未安装包，可以直接运行源码：

{ "version": 1, "servers": { "antd_mcp": { "command": "python", "args": ["-m", "server"], "cwd": "/path/to/antd-mcp/src", "timeoutSeconds": 60 } } }

注意：使用方式2时，需要确保：

已安装依赖：pip install -r src/requirements.txt
cwd 指向项目的 src 目录的绝对路径

环境变量

ANTD_MCP_CACHE_DIR 自定义缓存目录。
命令行参数:
- --color 启用彩色输出
- --pretty 启用 JSON 格式化输出

版本

当前版本: 0.1.1

常见问题 (FAQ)

ModuleNotFoundError: No module named 'antd_mcp'

已改为平铺布局，使用 python -m server 或安装后使用 antd-mcp-server。

输出出现多行 JSON 导致解析报错

仅解析第一行或使用流模式逐行处理。

想加速批量抓取

可后续新增并行与重试（Roadmap 中）。

如何发布新版本?

运行 ./scripts/release.sh <version>，确保环境变量与权限正确。

如何进行试发布(dry run)?

增加 --dry-run 参数，不上传、不推送。

如何本地测试安装?

使用 pipx install --force dist/antd_mcp_server-<version>-py2.py3-none-any.whl

Ant Design MCP Server