# ArkTS Docs MCP

ArkTS/ArkUI 官方文档搜索 MCP Server，基于 Augment 上下文引擎提供语义搜索能力。

## 功能概览

| 工具 | 功能 | 说明 |
|------|------|------|
| `search_context` | 语义搜索 | 基于 Augment 引擎搜索 1000+ 篇官方文档 |
| `read_document` | 文档阅读 | 根据文件名和分类读取完整 Markdown 内容 |
| `list_topics` | 分类浏览 | 列出开发指南和 API 参考的文档列表 |

## 快速开始

### 安装

```bash
npm install -g arkts-docs-mcp
```

### 配置 AI 助手

添加到 MCP 配置文件（Claude Desktop / Cursor / Windsurf 等）：

```json
{
  "mcpServers": {
    "arkts-docs": {
      "command": "npx",
      "args": [
        "arkts-docs-mcp",
        "--base-url", "YOUR_BASE_URL",
        "--token", "YOUR_TOKEN"
      ]
    }
  }
}
```

### 命令行参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `--base-url` | 是 | Augment 上下文引擎的 API 地址 |
| `--token` | 是 | 认证令牌 |
| `--enable-log` | 否 | 启用日志输出 |

## 工具说明

### search_context

搜索 HarmonyOS ArkTS 官方文档，返回语义匹配的文档内容。

**参数：**
- `query`（必填）：搜索关键词，支持中英文和自然语言
- `limit`（可选）：返回结果数量，默认 10，最大 50

**示例：**
```
search_context({ query: "State Prop 装饰器" })
search_context({ query: "Navigation 路由 页面跳转" })
search_context({ query: "List 列表组件", limit: 5 })
```

### read_document

读取文档的完整内容。通常在 `search_context` 返回摘要不够详细时使用。

**参数：**
- `filename`（必填）：文档文件名（不含 `.md` 后缀），从搜索结果的 Path 中提取
- `category`（可选）：`guides`（开发指南）或 `references`（API 参考），默认 `guides`

**示例：**
```
read_document({ filename: "arkts-state-management-best-practices", category: "guides" })
read_document({ filename: "arkts-apis-audio", category: "references" })
```

### list_topics

列出文档主题分类及文档列表。

**参数：**
- `category`（可选）：`guides` / `references` / `all`，默认 `all`

**示例：**
```
list_topics({})
list_topics({ category: "guides" })
```

## 使用示例

```
用户：@State 和 @Prop 有什么区别？
AI：→ search_context({ query: "State Prop 装饰器" })
    → read_document({ filename: "arkts-state", category: "guides" })
    @State 是组件私有状态，@Prop 是单向数据传递...
```

## 文档覆盖范围

包含 1000+ 篇官方 HarmonyOS 文档：
- ArkTS 语法特性和语言约束
- ArkUI 组件（Button、Text、List、Grid 等）
- 状态管理（@State、@Prop、@Link、@Observed 等）
- 动画和转场效果
- 导航和路由
- 系统 API 和能力

## 许可证

MIT