# AI tools reference

Source: https://docs.quake.ai/resources/ai-assisted-development/ai-tools-reference
Markdown: https://docs.quake.ai/resources/ai-assisted-development/ai-tools-reference.md
> Reference for the Quake AI MCP tool surface: callable tools, response envelope, export paths, JSON-RPC, and knowledge-graph.json schema.

---

# AI tools reference

This page documents the MCP tool surface, the response envelope, export paths, JSON-RPC, the `knowledge-graph.json` schema, and troubleshooting. For setup, see [How to connect AI tools to Quake AI docs](/resources/ai-assisted-development/ai-assisted-development). For a conceptual overview of what the server is and when to use each tool, see [What the MCP server is and why to use it](/resources/ai-assisted-development/what-is-the-mcp-server).

## MCP tools

The hosted MCP endpoint exposes nine callable tools. Cursor, Claude Desktop, and VS Code (with Copilot agent mode) can call them directly. Once configured, an IDE agent picks tools by intent. Describe what you want and the agent routes through the right tool. The reference below documents each tool's inputs, the response shape, and what to expect when nothing matches.

The endpoint requires no authentication. All tools read data only and back the public documentation surface. Rate limits apply per client IP.

### `search_docs`

Searches the Quake AI documentation corpus using BM25 plus knowledge graph traversal. Returns ranked pages with prerequisites, related operations, known issues, and workflow context.

**Inputs:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Search query for Quake AI documentation |

**Example prompt:**

> *"Search the Quake AI docs for how to configure a floating IP in OpenTofu."*

**Returns:** a `doc_reference` artifact whose `content` carries the full retrieval context (`seedPages`, `prerequisites`, `relatedOperations`) and whose `markdown_preview` renders the top result with prerequisites and related links wired as `[[wikilinks]]`.

**No matches:** the `markdown_preview` says so and points the reader at `https://docs.quake.ai`.

### `get_template`

Returns a validated OpenTofu HCL or Heat HOT template for a requested service. The tool retrieves a curated template from the library; it does not synthesize new HCL.

**Inputs:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `service` | string | yes | Service slug (for example `compute`, `network`, `storage`) |
| `format` | `"opentofu"` or `"heat"` | no | Filter by template format. Omit to accept either. |

**Example prompt:**

> *"Generate an OpenTofu template for a VM running Ubuntu 24.04 with 4 GB RAM, a security group allowing ports 22 and 80, and a floating IP."*

**Returns:** an `iac_template` artifact whose `content.templates[]` carries every matching template and whose `markdown_preview` renders the primary template's HCL (capped after 20 lines, with a link to the canonical docs URL for the full source).

**No matches:** the response includes `availableServices` (services that have templates) and `allTemplates` (every known template id, title, and service set) so the agent can suggest a valid alternative without inventing one.

### `validate_launch_manifest`

Validates a `quake.yaml` manifest (as parsed JSON): schema rules, flavor alias resolution, and service type to IaC template mapping. Returns structured errors and warnings without emitting a handoff packet.

**Inputs:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `manifest` | object | yes | Parsed `quake.yaml` as JSON (convert YAML to JSON before calling) |

**Example prompt:**

> *"Validate this quake.yaml manifest before I prepare a preview launch."*

**Returns:** a `validation_status` artifact whose `content` carries `{ valid, errors[], warnings[], resolved? }` and whose `markdown_preview` lists error paths, warnings (including `runtime: gpu`), and resolved flavor or template paths when valid.

**Invalid manifest:** `valid: false` with actionable `errors[]` entries (field path plus message). Fix errors before calling `prepare_launch`.

See [Launch handoff](/resources/ai-assisted-development/launch) and the [`quake.yaml` reference](/resources/ai-assisted-development/quake-yaml) for field definitions.

### `prepare_launch`

Validates a manifest, then returns a downloadable launch handoff packet for a human or control-plane consumer. The platform validates intent only; it does not run builds or deploys.

**Inputs:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `manifest` | object | yes | Parsed `quake.yaml` as JSON |
| `action` | enum | yes | `deploy`, `preview`, `promote`, or `rollback` |
| `source_sha` | string | no | Optional git commit SHA for the revision being launched |

**Example prompt:**

> *"Prepare a preview launch handoff for this quake.yaml on branch feature/login."*

**Returns:** on success, a `launch_handoff` artifact whose JSON `content` includes `request_id`, `action`, `manifest`, `resolved`, `evidence_bundle`, and `next_steps`, plus a Markdown preview summarizing environment, flavor, templates, and manual next steps.

**Invalid manifest:** same `{ valid: false, errors[], warnings[] }` shape as `validate_launch_manifest` with no handoff packet.

**Action requirements:** `preview` requires a `preview` environment entry; `deploy`, `promote`, and `rollback` require `production`. See [Launch handoff](/resources/ai-assisted-development/launch) for the branch workflow and evidence bundle stub.

### `export_okf`

Exports an [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) v0.1 knowledge sub-bundle for a Quake AI service or concept subtree: linked concept Markdown files plus an `index.md` for drop-in use in an Obsidian vault or any Markdown knowledge base. To save individual tool results to a notebook, see [How to save Quake AI knowledge to Obsidian, Git, or Notion](/resources/ai-assisted-development/save-to-obsidian-git-notion).

**Inputs:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `service` | string | no | Service slug to export (for example `compute`, `network`). Mutually exclusive with `concept`. |
| `concept` | string | no | Concept slug to export (for example `floating_ips`). Mutually exclusive with `service`. |
| `link_style` | `"bundle"` or `"obsidian"` | no | Link projection: `bundle` for canonical bundle-relative paths, `obsidian` for vault-relative paths. |

Provide exactly one of `service` or `concept`.

**Example prompt:**

> *"Export the Network service docs as an OKF bundle I can drop into my Obsidian vault."*

**Returns:** a `doc_reference` artifact whose `content` carries `{ service, concept, link_style, root_node_id, root_label, files[], validation_passed, validation_issues[] }`, where each file holds `{ relative_path, kind, content }` (`kind` is `concept`, `index`, `log`, or `root-index`). The `markdown_preview` renders the bundle's primary `index.md`.

**No selector:** when neither `service` nor `concept` is provided, the response asks for one. An unknown or ambiguous slug returns a message naming the problem rather than an empty bundle.

### `get_migration_mapping`

Resolves a competitor provider, a Quake AI service or concept slug, or a competitor node id, then returns the curated competitor analogs that map onto Quake AI with their divergence notes.

**Inputs:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | A competitor provider (for example `aws`), a Quake AI service or concept slug (for example `compute`), or a competitor node id |

**Example prompt:**

> *"Show how AWS networking maps onto Quake AI, with the divergences I should plan for."*

**Returns:** a `graph_query` artifact whose `content` carries `{ query, resolvedAs, entries[] }`. Each entry names the competitor term, its provider, the Quake AI concept or service it maps to, and any divergence notes. Provenance stays honest: a source URL and verification date appear only for human-verified records; every other entry reports as unverified. The `markdown_preview` lists each mapping with its divergences.

**No matches:** `entries` is empty and the preview suggests a provider (`aws`, `gcp`, `azure`), a service slug, or a concept slug.

### `get_workflow`

Returns the workflow ordering for a documentation page: its prerequisites, the pages that come before it, and the pages it leads to.

**Inputs:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `slug` | string | yes | A documentation page slug (for example `compute/how-to/create-vm`) |

**Example prompt:**

> *"What should I read before and after the create-a-VM how-to?"*

**Returns:** a `graph_query` artifact whose `content` carries `{ slug, pageId, title, requires[], before[], after[] }`, where each list holds `{ id, label, url }` steps. The `markdown_preview` renders three sections: Prerequisites, Comes after, and Leads to.

**No match:** when no page matches the slug, `content` is `null` and the preview says no page was found.

### `get_known_issues`

Returns the known error states for a Quake AI service, concept, or operation, plus the pages that resolve them.

**Inputs:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | A Quake AI service, concept, or operation slug, or a full node id |

**Example prompt:**

> *"What are the known issues with floating IPs, and which pages fix them?"*

**Returns:** a `graph_query` artifact whose `content` carries `{ query, nodeId, entries[] }`. Each entry is a known error state with its label and the resolution pages linked to it. The `markdown_preview` lists each issue with its resolution pages.

**No matches:** when no service, concept, or operation matches, `nodeId` is `null`; when a node matches but carries no recorded issues, `entries` is empty.

### `get_related`

Returns a knowledge-graph node's neighbors in any direction, optionally filtered to specific relation names.

**Inputs:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `node_id` | string | yes | A knowledge-graph node id (for example `service:compute`, `concept:floating-ip`, `page:compute/how-to/create-vm`) |
| `relations` | string[] | no | Relation names to filter to (for example `covers_concept`). Omit to return every relation. |

**Example prompt:**

> *"Show everything connected to the Compute service in the knowledge graph."*

**Returns:** a `graph_query` artifact whose `content` carries `{ nodeId, found, entries[] }`. Each entry names the relation, the direction (`out` or `in`), and the neighbor's id, type, label, and URL. The `markdown_preview` groups neighbors by relation.

**Edge cases:** when no node has the id, `found` is `false`; when the relation filter matches nothing, `entries` is empty.

## Response envelope

Every MCP tool wraps its result in the same `PortableArtifact` envelope. The MCP transport emits the full envelope as `structuredContent`; the `content[0].text` field carries the rendered Markdown that clients display.

| Field | Type | Description |
|---|---|---|
| `artifact_type` | enum | One of `doc_reference`, `iac_template`, `validation_status`, `launch_handoff`, or `graph_query` depending on the tool |
| `title` | string | Human-readable title |
| `content` | tool-specific | The raw payload. Shape depends on the tool that produced it. |
| `metadata.generated_at` | ISO 8601 | When the tool generated the artifact |
| `metadata.quake_ai_docs_url` | string or null | Canonical docs URL for the underlying content |
| `metadata.services_used` | string[] | Service slugs the artifact relates to |
| `metadata.tags` | string[] | Tags for the artifact |
| `metadata.source` | const | Always `"knowledge-graph"` |
| `export.markdown_preview` | string | Pre-rendered Markdown: title, body, and a link to the canonical docs page |

The `markdown_preview` is a copy of `content[0].text`. IaC code blocks longer than 20 lines truncate inline and append a pointer to the canonical docs URL, so the preview fits on screen and links to the source of truth rather than replacing it.

Example response from `search_docs` with query `"floating IP"`:

```json
{
  "artifact_type": "doc_reference",
  "title": "Search results for \"floating IP\"",
  "content": {
    "query": "floating IP",
    "results": {
      "seedPages": [
        {
          "title": "Allocate a floating IP",
          "slug": "network/how-to/allocate-floating-ip",
          "url": "/docs/network/how-to/allocate-floating-ip",
          "snippet": "Floating IPs map a public address onto a private port..."
        }
      ],
      "prerequisites": [{ "title": "Create a VPC" }],
      "relatedOperations": [{ "label": "Attach a floating IP" }]
    }
  },
  "metadata": {
    "generated_at": "2026-05-08T11:20:15.000Z",
    "quake_ai_docs_url": "https://docs.quake.ai/docs/network/how-to/allocate-floating-ip",
    "services_used": ["network"],
    "tags": ["docs", "quake-ai"],
    "source": "knowledge-graph"
  },
  "export": {
    "markdown_preview": "# Allocate a floating IP\n\nFloating IPs map a public address..."
  }
}
```

## Calling the endpoint directly

If you are not using an IDE client, call the endpoint as plain JSON-RPC.

- **Endpoint:** `POST https://docs.quake.ai/api/mcp`
- **Transport:** Streamable HTTP per the MCP specification. No session ID required.
- **Auth:** none.
- **`GET`:** returns 405 with a JSON-RPC error body. Use `POST`.

Example `curl` invocation of `search_docs`:

```bash
curl -sS https://docs.quake.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_docs",
      "arguments": { "query": "floating IP" }
    }
  }'
```

The response carries the rendered Markdown in `result.content[0].text` and the full `PortableArtifact` envelope in `result.structuredContent`.

## `knowledge-graph.json` schema

The knowledge graph is a static JSON file regenerated at build time from MDX frontmatter and a competitor-divergences config. It is the structured layer behind on-site search, the MCP server's retrieval, the `<SeeAlso>` panel, prerequisite chains, and migration callouts.

**Endpoint:** [`https://docs.quake.ai/knowledge-graph.json`](https://docs.quake.ai/knowledge-graph.json)

**Top-level shape:**

```json
{
  "generated": "2026-05-23T13:42:00.000Z",
  "stats": { "nodes": 1136, "edges": 6538, "pages": 306, "services": 14, "concepts": 195, "competitors": 313, "templates": 15, "tools": 26 },
  "nodes": [ /* 1,136 nodes */ ],
  "edges": [ /* 6,538 edges */ ]
}
```

### Node types

| Type | What it represents | Approximate count |
|---|---|---|
| `page` | One published documentation page | 306 |
| `service` | A Quake AI service (Compute, Network, Storage, Kubernetes, etc.) | 14 |
| `concept` | A reusable concept (floating IP, security group, flavor) | 195 |
| `competitor` | A service from another cloud (AWS EC2, GCP Compute Engine) | 313 |
| `template` | An IaC template (OpenTofu / Heat) | 15 |
| `tool` | A CLI or SDK | 26 |
| `operation` | A documented operation verb | 22 |
| `error_state` | A named error class | 14 |
| `api_endpoint` | An authoritative API endpoint | 4 |
| `region` | A deployment region | 1 |
| `managed_service` | A managed-service availability marker | 1 |
| `content_type` | A content-type taxonomy node (`how-to`, `concept`, `reference`, etc.) | 7 |
| `faq_item` | One Q&A from a service FAQ | 209 |
| `openstack_project` | The OpenStack project a Quake AI service is backed by | 9 |

Every node has at minimum `{ id, type, label }`. Page nodes carry `metadata.url`, `metadata.service`, `metadata.personas`, `metadata.competitor_analogs`, `metadata.difficulty`, `metadata.last_validated`, and other frontmatter-derived fields. The full page prose is not embedded in the graph; it lives in a separate `kg-text-index.json` artifact that backs search.

### Edge relations

Every edge has `{ source, target, relation }`. Some carry `metadata` (used for competitor `diverges_from` divergence lists) and `provenance` (source URL, last verified date).

| Relation | Approximate count | What it means |
|---|---|---|
| `maps_to` | 1,582 | A competitor service maps to a Quake AI concept or service |
| `documented_at` | 1,202 | A concept is documented on a specific page |
| `covers_concept` | 1,198 | A page covers a concept |
| `analog_of` | 880 | A service or concept has an analog in another cloud |
| `belongs_to_service` | 328 | A page belongs to a service |
| `has_type` | 306 | A page has a content-type taxonomy |
| `has_faq_item` | 209 | A service has an FAQ item |
| `diverges_from` | 156 | A Quake AI concept diverges from a competitor (carries divergence list and provenance) |
| `requires` | 117 | A page requires a prerequisite |
| `parameterized_by` | 68 | A template is parameterized by a concept |
| `compatible_with` | 58 | A tool is compatible with a service |
| `provisions` | 35 | A template provisions a service |
| `has_known_issue` | 32 | A concept or operation has a known issue |
| `documents_operation` | 25 | A page documents an operation |
| `answers` | 299 | An FAQ item answers about a concept |
| `resolved_by` | 14 | A known issue is resolved by a specific page |
| `implemented_by` | 9 | A managed service is implemented by an OpenStack project |
| `url_alias` | 8 | A page has a URL alias |
| `precedes` | 7 | A page precedes another in a learning order |
| `has_api_ref` | 4 | A service has an API reference page |
| `bridges` | 1 | Two services bridge through a third concept |

### Example node

A real `page` node (truncated for length):

```json
{
  "id": "page:network/concepts/floating-ips",
  "type": "page",
  "label": "Floating IPs",
  "url": "https://docs.quake.ai/docs/network/concepts/floating-ips",
  "metadata": {
    "content_type": "explanation",
    "service": "network",
    "personas": ["new_user", "devops_engineer", "developer", "architect"],
    "managed_service_status": "not_yet_available",
    "competitor_analogs": [
      "aws_elastic_ip", "azure_public_ip", "gcp_static_external_ip"
    ],
    "estimated_time": "8 minutes",
    "last_validated": "2026-05-19"
  }
}
```

### Example edge (with divergence metadata)

```json
{
  "source": "concept:floating_ips",
  "target": "competitor:aws_elastic_ip",
  "relation": "diverges_from",
  "metadata": {
    "provider": "aws",
    "term": "Elastic IP addresses",
    "divergences": [
      "AWS charges idle EIPs.",
      "OpenStack floating IPs free/pool-limited.",
      "AWS regional instance/ENI.",
      "OpenStack project port."
    ],
    "confidence": "high",
    "doc_url": "https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html"
  }
}
```

### Common queries

| Query | Approach |
|---|---|
| All pages on a service | Filter edges by `relation == "belongs_to_service"` and `target == "service:{slug}"` |
| All concepts covered by a page | Filter edges by `source == "page:{slug}"` and `relation == "covers_concept"` |
| All AWS analogs for a service | Filter edges by `source == "competitor:aws_*"`, `target == "service:{slug}"`, `relation == "maps_to"` |
| All known issues for a concept | Filter edges by `source == "concept:{slug}"`, `relation == "has_known_issue"` |
| All templates that take a concept as a parameter | Filter edges by `target == "concept:{slug}"`, `relation == "parameterized_by"` |

## Troubleshooting

**The MCP server does not appear in the IDE's tool list.** Restart the IDE after editing its config file. Cursor reads `.cursor/mcp.json` at startup; Claude Desktop reads `claude_desktop_config.json` at startup; VS Code with Copilot agent mode reads `.vscode/mcp.json`. Confirm the file is valid JSON and the URL is reachable from the machine running the IDE.

**`search_docs` returns no results.** Try a broader query and prefer service vocabulary the docs use (for example `floating IP`, `block volume`, `flavor`). The corpus indexes published documentation only; private notes and internal wikis are not searchable here.

**`get_template` returns a list of available services instead of HCL.** No template matches the requested service or format. The response carries `availableServices` and `allTemplates` so the agent can pick a valid service and retry. If you expected a template to exist, check the [automation templates index](/resources/iac-templates).

**The agent generated content about the video platform "Quake AI" instead of Quake AI.** Add the disambiguation rule to your system prompt or rules file. See [How to connect AI tools to Quake AI docs](/resources/ai-assisted-development/ai-assisted-development).