# mcp-taro-docs

An MCP (Model Context Protocol) server for **Taro official docs** (https://docs.taro.zone).

It exposes a 2-step retrieval workflow:
- Query candidates from the docs sitemap (query)
- Fetch full page content by `asset_id` (get)

## Tools

### taro-official-query-assets

Filters and ranks candidate doc pages from `https://docs.taro.zone/sitemap.xml` (URL matching + lightweight scoring).

Arguments:
- `query` (required): Query string
- `top_k` (optional, default 10, max 50): Maximum number of candidates to return
- `pathPrefix` (optional): Path prefix to narrow the search scope, e.g. `/docs/components`
- `caseSensitive` (optional, default false): Whether to use case-sensitive matching

Returns:
- `results[]`: items include `asset_id`, `url`, `file_path`, `score`, etc.

### taro-official-get-assets

Fetches the full doc page text by `asset_id`.

Arguments:
- `asset_ids` (required): `asset_id` list returned by `taro-official-query-assets` (max 10)

Returns:
- `contents[]`: items include `title`, `url`, `file_path`, `content` (plain text), etc.

## Local build & run

Requires: Node.js >= 18

```bash
cd /Users/bytedance/Downloads/taro-docs/mcp-taro-docs
npm install
npm run build
```

Build output:
- `dist/index.cjs` (CommonJS, usable as the MCP Server entrypoint)

## Quick test (stdio JSON-RPC)

### 1) List tools

```bash
node dist/index.cjs <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
EOF
```

### 2) Query then get (CoverImage example)

```bash
node dist/index.cjs <<'EOF'
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"taro-official-query-assets","arguments":{"query":"cover-image","top_k":5,"pathPrefix":"/docs/components"}}}
EOF
```

Copy `results[0].asset_id` from the output, then call get:

```bash
node dist/index.cjs <<'EOF'
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"taro-official-get-assets","arguments":{"asset_ids":["<asset_id>"]}}}
EOF
```

## MCP client config examples

### Cursor (mcp.json)

```json
{
  "Taro Official Docs": {
    "command": "node",
    "args": ["/Users/bytedance/Downloads/taro-docs/mcp-taro-docs/dist/index.cjs"]
  }
}
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "taro-official-docs": {
      "command": "node",
      "args": ["/Users/bytedance/Downloads/taro-docs/mcp-taro-docs/dist/index.cjs"]
    }
  }
}
```

## Notes

- `asset_id` is a stable hash of the page URL (same URL => same `asset_id`)
- `pathPrefix` is a scope filter; it does not need to equal the full path
- The sitemap is cached in-memory per process (restart to refresh)