Skip to content
Charming Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Technical specs for agents

Dense build, runtime, and protocol specs written for agents that work with Charming.

These specs are written for agents and client implementers. You can read them, but they are dense and assume the reader can call MCP tools or make HTTP requests.

Protocol references

  • REST API reference: the OpenAPI contract rendered by operation.
  • MCP reference: the generated standard and ChatGPT MCP contracts, including every tool, prompt, resource, and schema.
  • Browser runtime API: every app-author method and property on window.charming.
  • Authentication: token scopes, pairing, claims, recovery, and revocation.
  • External files and CSP: uploaded files, remote origins, browser policy, and unsupported resource types.

Task prompts

Read docs through MCP

An agent connected to Charming can read public documentation with read_docs, using the same authenticated MCP connection as the app tools. It needs no browser access or second connector. The server reads from the same docs origin as this site; app data and source are still read through query_app and get_app_source.

  1. The MCP client discovers read_docs through tools/list. Its description tells the agent when to use it. Connecting does not put the full docs into the agent’s context; the agent calls the tool when it needs a reference.
  2. Call read_docs({}) to get the docs index. An empty path also opens the index. Choose a relevant page from its links. If the page path is already known, skip the index.
  3. Pass the portion after /docs/, such as read_docs({ path: "capabilities/data-storage.md" }). A copied path with the docs/ prefix also works. Do not pass the full URL, query string, or fragment. A page slug without .md also works.
  4. Read the returned markdown. The response also includes the normalized path, canonical url, and next_offset. Each chunk contains at most 20,000 characters. When next_offset is not null, call again with the returned path and that value as offset; continue until it is null.
  5. Apply the guidance, then use the app tools to complete the task. Reading docs does not create or change an app.

For example, an agent building a new app can read build-mcp.md, then prompts/design-an-app.md, before calling create_app. llms-full.txt is the full authoring reference. The existing charming:app-guide and charming:design-guide MCP prompts remain available in clients that support prompts; read_docs also works in clients that expose only tools. It reads an index or a page, rather than searching the docs by keyword.

Failed reads return isError: true with a stable error kind:

Kind Recovery
invalid_request Use a doc path without a URL, query, or fragment. If the offset exceeds the document length, restart at offset 0.
not_found Read the index again and choose an available page.
operation_failed The docs could not be read. Retry shortly; do not guess what the missing page says.
rate_limited Wait briefly, then retry. Each server process permits 60 reads per authenticated caller per minute.

Reads time out after ten seconds and reject redirects and HTML responses. Each chunk fetches the current page and counts as one read, so a docs deployment between calls can shift offsets; restart at 0 if the content no longer lines up.

Was this page helpful?