Hanzi Write

基于 xmcp 框架的 MCP 工具集，包含汉字笔顺动画练习和实时天气查询。

功能特性

• 汉字笔顺动画播放与描红练习
• 全球主要城市实时天气查询
• React + TypeScript + Tailwind CSS v4
• 支持 HTTP 传输模式
• Docker 容器化部署
• 内置测试框架（vitest）

环境要求

• Node.js >= 20.0.0
• npm

快速开始

npm install
npm run dev

开发服务器启动后，MCP 服务将通过 HTTP 模式运行。

可用的 MCP 工具

1. hanzi-writer（汉字笔顺练习）

• 描述：汉字笔顺动画和描红练习
• 参数：
  • character (string, 默认: "永") - 要练习的汉字

2. weather（天气查询）

• 描述：查询全球主要城市的实时天气
• 支持城市：Buenos Aires, San Francisco, Berlin, Tokyo, New York

项目脚本

命令	说明
npm run dev	启动开发服务器
npm run build	生产环境构建
npm start	启动生产服务
npm run typecheck	TypeScript 类型检查
npm test	启动测试（watch 模式）
npm run test:ci	一次性运行测试
npm run clean	清理构建产物

更多命令请查看 commands.txt。

项目结构

hanzi-write/
├── src/
│   ├── lib/           # 共享逻辑
│   │   ├── constants.ts
│   │   ├── weather-client.ts
│   │   └── hanzi-writer-loader.ts
│   └── tools/         # MCP 工具
│       ├── weather.tsx
│       └── hanzi-writer.tsx
├── tests/             # 测试文件
├── web/               # Next.js 预览端
├── Dockerfile
├── commands.txt
├── structure.txt
└── package.json

详细结构说明请查看 structure.txt。

环境变量

复制 .env.example 为 .env 并按需修改：

cp .env.example .env

变量	说明	默认值
OPEN_METEO_BASE_URL	Open-Meteo API 地址	https://api.open-meteo.com
HANZI_WRITER_CDN	HanziWriter CDN 地址	jsDelivr

Docker 部署

docker build -t hanzi-write-mcp .
docker run -p 3000:3000 hanzi-write-mcp

Web 预览

项目包含一个 Next.js 预览页面，用于在浏览器中查看 MCP UI：

cd web
npm install
npm run dev

然后访问 http://localhost:3000。

技术栈

• 框架：xmcp
• UI：React 19 + TypeScript
• 样式：Tailwind CSS v4
• 测试：Vitest
• 部署：Docker

许可证

MIT