# MCP

OpenHarmony 文档写作 MCP（Model Context Protocol）服务，将本文档站点的「风格指南」和「文档模板」以工具的形式提供给 AI 助手，让开发者在用 AI 工具（Claude、Cursor 等）撰写 OpenHarmony 技术文档时，能够按需查询写作规范、获取文档模板。

## 配置方式

MCP 服务端点（streamable HTTP）：

```
https://openharmony.tw.cn/mcp
```

### Claude Desktop

编辑 `claude_desktop_config.json`（Claude → 设置 → 开发者 → Edit Config）：

```json
{
  "mcpServers": {
    "harmonyos-docs": {
      "type": "http",
      "url": "https://openharmony.tw.cn/mcp"
    }
  }
}
```

### Cursor

在项目根目录创建 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "harmonyos-docs": {
      "url": "https://openharmony.tw.cn/mcp"
    }
  }
}
```

### OpenCode

在项目根目录的 `opencode.json` 中添加（或全局配置 `~/.config/opencode/opencode.json`）：

```json
{
  "mcp": {
    "harmonyos-docs": {
      "type": "remote",
      "url": "https://openharmony.tw.cn/mcp",
      "enabled": true
    }
  }
}
```

> 注：不同客户端对 streamable HTTP 的配置字段略有差异（部分用 `type: "http"`，部分直接填 `url`），以上为通用写法。配置后重启客户端，即可在 AI 对话中调用下述工具。

## 支持的 Tool

### 1. `list_templates`

列出所有可用的文档模板类型（英文 type + 中文标题）。

无参数。返回 12 个模板类型，例如：

```
- guide: 开发指南写作模板
- faq: FAQ写作模板
- js: API接口说明模板
- ts: ArkTS组件接口说明模板
- native: Native接口文档注释
- readme: xxx子系统/部件
- ...
```

### 2. `get_template`

获取指定类型的文档模板全文。

| 参数 | 说明 |
|---|---|
| `type` | 模板类型，见 `list_templates` 的返回值 |

示例：`get_template(type="guide")` 返回「开发指南写作模板」的完整框架与写作要求。

### 3. `list_style_topics`

列出文档风格指南的所有主题（按 `##` 小节切分，含所属章节）。

无参数。返回 32 个主题，例如：

```
- 标题（文档结构）
- 段落（文档结构）
- 表格（内容元素）
- 图片（内容元素）
- 人称及语态（语言风格）
- 简洁（语言风格）
- ...
```

### 4. `get_style_rule`

获取指定主题的写作规则。

| 参数 | 说明 |
|---|---|
| `topic` | 主题名，见 `list_style_topics` 的返回值 |

示例：`get_style_rule(topic="表格")` 返回表格相关的所有写作规则（含正反例）。

### 5. `search_docs`

在全部文档内容中按关键词搜索（所有关键词都需匹配）。

| 参数 | 说明 |
|---|---|
| `query` | 关键词，多个关键词用空格分隔（AND 语义）|

示例：`search_docs(query="API 接口")` 返回匹配文档的标题、路径与内容片段。

## 典型使用流程

AI 助手在帮助撰写文档时，通常按以下顺序调用：

1. `list_templates` → 确定要写的文档类型
2. `get_template(type)` → 拿到模板框架
3. `list_style_topics` → 了解可查询的写作规范主题
4. `get_style_rule(topic)` → 查询具体写作规则
5. `search_docs(query)` → 不确定时全文搜索兜底

## 后续规划

### B 类：校验类工具（计划中）

| tool | 用途 |
|---|---|
| `check_markdown` | Markdown 格式检查（中英文空格、标点等，接 lint-md）|
| `validate_document` | 风格规范校验（标题层级、句式、必备章节）|

### C 类：智能类工具（计划中）

| tool | 用途 |
|---|---|
| `suggest_rewrite` | 对文字给出符合风格的改写建议（需 MCP 服务内部调用 LLM）|