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

安装后命令行入口：

# 使用管道输入 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 流式 JSON-RPC）
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

脚本步骤:

1. 检查 git 工作区是否干净
2. 运行测试
3. 更新 pyproject.toml 中版本号
4. 提交并打 tag v<version>
5. 构建 (wheel + sdist)
6. twine check 验证
7. 上传 (跳过若 dry-run)
8. 推送 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)

1. ModuleNotFoundError: No module named 'antd_mcp'

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

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

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

3. 想加速批量抓取

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

4. 如何发布新版本?

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

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

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

6. 如何本地测试安装?

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

antd-mcp