# 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):
```bash
# 使用管道输入 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
```bash
# 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)

## 安装 (发布后)

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

安装后命令行入口：

```bash
# 使用管道输入 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 请求。

## 本地构建与发布

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

### 自动化脚本

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

```bash
# 正常发布新版本 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):
  ```bash
  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：使用已安装的包（推荐）

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

然后配置 mcp.json：
```jsonc
{
  "version": 1,
  "servers": {
    "antd_mcp": {
      "command": "antd-mcp-server",
      "args": [],
      "timeoutSeconds": 60
    }
  }
}
```

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

如果未安装包，可以直接运行源码：
```jsonc
{
  "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