ragora

使用 Ragora MCP 工具和 REST API 从知识库中发现、搜索和综合答案。当用户要求 Ragora 集合、跨集合比较、来源支持的摘要、尽职调查研究或使用市场数据进行验证时触发。

## 概述（中文）

使用 Ragora MCP 工具和 REST API 从知识库中发现、搜索和综合答案。当用户要求 Ragora 集合、跨集合比较、来源支持的摘要、尽职调查研究或使用市场数据进行验证时触发。

## 原文

# Ragora Skill for OpenClaw

Use this skill to answer questions with Ragora data. You have two integration paths:

1. **MCP (Model Context Protocol)** — preferred when your client supports MCP tool binding.
2. **REST API** — use directly via HTTP when MCP is unavailable or when you need fine-grained control.

Both paths share the same authentication, data model, and search capabilities.

## Source of Truth Docs

Consult these docs first when behavior differs across environments:

- MCP guide: `https://ragora.app/docs?section=mcp-guide`
- Getting started: `https://ragora.app/docs?section=getting-started`
- API overview: `https://ragora.app/docs?section=api-overview`
- Retrieve API: `https://ragora.app/docs?section=api-retrieve`
- Errors and limits: `https://ragora.app/docs?section=api-errors`
- Billing API: `https://ragora.app/docs?section=api-billing`

---

## Core Concepts

Before using any tools, understand the Ragora data model.

### Collections

A **collection** is a knowledge base — a curated set of documents indexed for semantic search. Each collection has:

- **Name** — human-readable label (e.g., "Employee Handbook").
- **Slug** — URL-safe identifier used in dynamic tools and API paths (e.g., `employee_handbook`).
- **Description** — what the collection contains and when to use it.
- **Stats** — document count, chunk count, last updated timestamp.

### Documents & Chunks

Each collection contains **documents** (files, pages, articles). Documents are split into **chunks** — small passages optimized for semantic retrieval. When you search, results are returned at the chunk level with metadata pointing back to the source document.

### Versions

Some collections support **versioned documentation** (e.g., API docs v1.0, v2.0). Use `list_versions_{slug}()` or the API to discover available versions, then pass a `version` parameter to scope your search.

### Tags & Filters

Collections may support:

- **Custom tags** — string labels attached to documents (e.g., `["legal", "msa", "2024"]`). Pass as `custom_tags` to narrow results.
- **Filters** — key-value metadata filters (e.g., `{"region": "US", "department": "engineering"}`). Pass as `filters` to constrain results.

### Credits & Billing

- **Own collections and subscriptions** — free MCP/API access, no credit cost.
- **Marketplace products (pay-per-use)** — each retrieval deducts credits based on seller pricing.
- Credits are measured in USD. Check with `check_balance()` or `GET /v1/billing/balance`.
- Top up at `https://app.ragora.app/settings/billing`.

---

## Connection Setup

### Authentication

All requests (MCP and REST) require a Ragora API key.

- **Format**: `sk_live_<uuid>` (e.g., `sk_live_a1b2c3d4-e5f6-7890-abcd-ef1234567890`)
- **Create one**: `https://app.ragora.app/settings/api-keys`
- **Shown once** — copy and store it securely at creation time.
- **Hashed on server** — SHA-256 + bcrypt. Ragora cannot recover a lost key; generate a new one.

### Security rules

- Never pass API keys in URL query parameters.
- Never print full API keys in logs, outputs, or final answers.
- If the key is missing or invalid, stop and ask the user for a valid key.
- Mask keys in any debug output: `sk_live_****...`.

### MCP endpoint

- **URL**: `https://mcp.ragora.app/mcp`
- **Auth header**: `Authorization: Bearer <RAGORA_API_KEY>`

OpenClaw config (YAML):

```yaml
name: ragora
type: http
url: https://mcp.ragora.app/mcp
headers:
  Authorization: Bearer ${RAGORA_API_KEY}
```

Claude Desktop / Cursor / VS Code config (JSON):

```json
{
  "mcpServers": {
    "ragora": {
      "type": "http",
      "url": "https://mcp.ragora.app/mcp",
      "headers": {
        "Authorization": "Bearer ${RAGORA_API_KEY}"
      }
    }
  }
}
```

> **Security note**: Set `RAGORA_API_KEY` as an environment variable in your OS or secret manager. Never hardcode the raw `sk_live_*` value in config files that may be committed to version control.

### REST API base URL

- **Base**: `https://api.ragora.app/v1`
- **Auth header**: `Authorization: Bearer <RAGORA_API_KEY>`
- **Content-Type**: `application/json` for all POST/PUT requests.

---

## Connectivity Check (Run First)

### Via MCP

1. Confirm server health:

```bash
curl -s https://mcp.ragora.app/health
```

2. Call `discover_collections()`. If it returns collections, you're connected.

3. If empty — user may need to access a knowledge base: `https://ragora.app/marketplace`

4. If credits are low — call `check_balance()` and tell user to top up at `https://app.ragora.app/settings/billing`.

### Via REST API

1. Confirm server health:

```bash
curl -s https://api.ragora.app/v1/health
```

2. List collections:

```bash
curl https://api.ragora.app/v1/collections \
  -H "Authorization: Bearer <RAGORA_API_KEY>"
```

3. If the response is `401` or `403`, the API key is invalid or expired. Ask the user to generate a new one.

---

## Operating Rules

- Start with `discover_collections()` (MCP) or `GET /v1/collections` (API) before targeted retrieval, unless the user explicitly names a known collection.
- Prefer targeted collection search over global search once you know the likely collections.
- Use global search for broad exploration only — ambiguity, unknown source, or discovery pass.
- Keep retrieval iterative: run multiple focused queries instead of one long query.
- Include source attribution from returned results in final answers.
- Call out uncertainty when evidence is partial, conflicting, or missing.
- If credits are low or errors mention billing limits, check balance and report constraints.
- Choose MCP tools when available; fall back to REST API when MCP binding fails or when you need features not exposed via MCP (e.g., pagination, collection metadata).

---

## MCP Tools Reference

### Static tools (always available)

| Tool | Parameters | Description |
|------|-----------|-------------|
| `discover_collections()` | none | List all accessible knowledge bases with descriptions, stats, available operations, and usage examples. |
| `search(query, top_k?)` | `query` (required), `top_k` (1-20, default 5) | Search across ALL accessible collections at once. |
| `search_collection(collection_name, query, top_k?, custom_tags?, filters?)` | `collection_name` (required), `query` (required), `top_k` (1-20, default 5), `custom_tags` (list of strings), `filters` (object) | Search a specific collection by name or slug. |
| `check_balance()` | none | Credits remaining and estimated USD value. |

### Dynamic tools (per-collection, returned in manifest)

The Gateway generates these tools for each collection you have access to. The `{slug}` is the collection's URL-safe name (e.g., `employee_handbook`, `k8s_troubleshooting`).

| Tool | Parameters | Description |
|------|-----------|-------------|
| `search_{slug}(query, top_k?, version?, custom_tags?, filters?)` | `query` (required), `top_k` (1-20, default 5), `version` (optional string), `custom_tags` (list of strings), `filters` (object) | Semantic search within the collection. |
| `get_topic_{slug}(topic)` | `topic` (required string) | Retrieve information about a specific topic from the collection. |
| `list_versions_{slug}()` | none | List all available documentation versions for the collection. |

### MCP Resources

| URI | Description |
|-----|-------------|
| `ragora://collections` | Lists all accessible collections with metadata, stats, and available operations. |

### MCP Prompts

| Prompt | Parameters | Description |
|--------|-----------|-------------|
| `search_collection_prompt` | `collection_name`, `query` | Pre-built prompt for searching a specific collection. |
| `summarize_collection` | `collection_name` | Pre-built prompt for summarizing an entire collection. |
| `compare_sources` | `collection_names`, `question` | Pre-built prompt for comparing information across multiple collections. |

---

## REST API R