# ant-design GitHub MCP Demo

一个最简单的 TypeScript MCP Server，通过 GitHub REST API 实时读取 `ant-design/ant-design`。

## 安装和运行

```bash
npm install
npm run build
npm start
```

可选：设置 `GITHUB_TOKEN`，提高 GitHub API 的请求额度：

```bash
GITHUB_TOKEN=ghp_xxx npm start
```

提供 3 个 MCP tools：

- `get_repository`：读取仓库信息
- `list_directory`：读取目录列表
- `read_file`：读取文本文件

每次工具调用都会请求 GitHub API，因此不是本地 clone 的静态副本。

## 直接运行演示

如果暂时没有接入 MCP 客户端，可以直接运行命令行 Demo。它会实时读取仓库信息、根目录和 `package.json`：

```bash
npm run demo
```

演示代码位于 [src/demo.ts](src/demo.ts)，与 MCP Server 共用 GitHub 请求逻辑。

## AI Agent + MCP 完整演示

真正的 Agent 演示位于 [src/agent.ts](src/agent.ts)。它会：

1. 启动当前 MCP Server
2. 通过 MCP Client 发现 Server 暴露的 tools
3. 把 tools 提供给 OpenAI 模型
4. 模型自主决定调用哪个 MCP tool
5. Agent 通过 MCP Client 执行工具，并把结果交回模型

先在项目根目录的 `.env.local` 中填写 DeepSeek API Key：

```dotenv
DEEPSEEK_API_KEY=你的_deepseek_api_key
DEEPSEEK_MODEL=deepseek-v4-flash
```

然后运行：

```bash
npm install
npm run build
npm run agent
```

也可以传入自己的问题：

```bash
npm run agent -- "读取 ant-design 的 components/button/button.tsx，并总结它的主要逻辑"
```

如果需要更换模型，可以修改 `.env.local`：

```bash
DEEPSEEK_MODEL=deepseek-v4-pro npm run agent
```

运行时你会看到类似链路：

```text
Agent 已通过 MCP Client 连接 MCP Server
发现工具：get_repository, list_directory, read_file
Agent → MCP Server: list_directory({"path":"components/button"})
MCP Server → Agent: {"content":[...]}
最终回答：...
```

## MCP 客户端配置

当前项目根目录已经提供 `.mcp.json`，其中同时配置了 `antd-docs` 和 `weather`。先构建项目：

```bash
npm run build
```

然后在这个项目根目录启动 Claude Code，它会读取根目录的 `.mcp.json`。如果把配置复制到其他项目，需要把 `args` 中的路径改成已发布的 GitHub/npm 启动命令，或者改成新的绝对路径。

注意：`.mcp.json` 是 Claude Code 的项目级配置；Codex 不会自动读取它。Codex 需要单独执行 `codex mcp add`，或配置 `~/.codex/config.toml`。

构建后，将下面配置加入客户端的 MCP 配置文件，并把路径替换为本项目的绝对路径：

```json
{
  "mcpServers": {
    "antd-github-reader": {
      "command": "node",
      "args": ["/Users/你的用户名/mcp-demo/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "可选的 GitHub Token"
      }
    }
  }
}
```

## 发布到 GitHub 并在任意项目复用

将项目推送到 GitHub 后，可以通过统一 CLI 启动两个 Server。下面的 `YOUR_GITHUB_USERNAME/antd-weather-mcp` 替换成你的 GitHub 仓库：

```bash
npx -y github:YOUR_GITHUB_USERNAME/antd-weather-mcp antd
npx -y github:YOUR_GITHUB_USERNAME/antd-weather-mcp weather
```

### Codex 全局配置

将 Server 加到用户级配置后，在任意项目都可使用：

```bash
codex mcp add antd-docs -- npx -y github:YOUR_GITHUB_USERNAME/antd-weather-mcp antd
codex mcp add weather -- npx -y github:YOUR_GITHUB_USERNAME/antd-weather-mcp weather
codex mcp list
```

### Claude Code 全局配置

使用 `--scope user` 将 Server 配置到用户级别：

```bash
claude mcp add --scope user antd-docs -- npx -y github:YOUR_GITHUB_USERNAME/antd-weather-mcp antd
claude mcp add --scope user weather -- npx -y github:YOUR_GITHUB_USERNAME/antd-weather-mcp weather
claude mcp list
```

之后在任意项目启动 Codex 或 Claude Code，都可以让 AI 查询 ant-design 文档或天气：

```text
查一下 ant-design Button 组件的 API，并查询旧金山未来天气。
```

### 发布到 npm（可选）

如果希望命令更短、安装更稳定，可以先把 `package.json` 的 `name` 改成一个未占用的 npm 包名，然后发布：

```bash
npm login
npm publish --access public
```

发布后可使用：

```bash
npx -y 你的npm包名 antd
npx -y 你的npm包名 weather
```

例如可以让客户端调用：

```text
读取 ant-design 仓库 components/button 目录，并打开其中的 index.tsx
```

## 开发模式

```bash
npm run dev
```

## 天气 MCP Server

参考 [MCP 天气服务器 Quickstart](https://modelcontextprotocol.info/zh-cn/docs/quickstart/server/)，项目新增了独立的 [src/weather.ts](src/weather.ts)。它使用 `stdio` 提供两个 MCP 工具：

- `get_alerts`：查询美国州级天气预警，例如 `CA`、`NY`
- `get_forecast`：根据经纬度查询未来天气预报

编译后可以单独启动：

```bash
npm run build
npm run weather
```

在 Claude Desktop 或其他 MCP 客户端中加入：

```json
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/Users/你的用户名/mcp-demo/dist/weather.js"]
    }
  }
}
```