capacities-mcp-best-practice

Capacities MCP Best Practices

Use this skill as the operating manual for the Capacities MCP server. Assume no prior knowledge of Capacities. Treat the server's current tool schemas and live inspect_space output as authoritative when they are more specific than this guide.

Load only the references needed

• Read references/tools.md before selecting or calling a tool. It documents all tools and parameters.
• Read references/properties-and-objects.md when working with structures, properties, fields, collections, dates, labels, entities, aliases, or icons.
• Read references/structural-content.md before constructing or editing structured blocks or tokens.
• Read references/markdown-and-entities.md before any Markdown write or when interpreting Markdown output.
• Read references/responses-errors-and-recovery.md before a mutation, and whenever a call fails, is unverified, is partial, or is rate-limited.

Do not load every reference for a simple read-only lookup.

Mental model

Capacities stores typed objects inside a space:

• A structure is an object type, such as Page, Tag, Task, or a custom type.
• A structure defines typed properties. Object property values must conform to the live definition.
• An object can belong to zero or more collections.
• Object body content is a tree of blocks. Rich text inside blocks is an ordered array of tokens.
• Markdown is a convenient, intentionally lossy representation of body content. It does not replace typed properties or exact block editing.

Never infer a custom structure, property ID, label option, collection ID, or target object ID from a display name alone when live discovery can resolve it.

Required workflow

1. Interpret the request. Separate object metadata, typed properties, collections, body content, and destructive intent. Determine whether the user wants a read, an append, an exact edit, or replacement.
2. Discover the live model. Call inspect_space. For a write to a named or unfamiliar structure, request that structure's full definition and write guide. Use refresh: true only when definitions may have changed during the session.
3. Resolve existing objects. Use search_objects for title discovery, then get_object by UUID. Search is title-only and is not proof of object contents.
4. Choose a content representation. Use the decision table below. Do not mix Markdown assumptions into structural edits.
5. Construct a valid payload. Use live property definitions plus the exact schemas in the references. Omit unchanged values. Treat supplied property arrays and child arrays as replacements where documented.
6. Establish a before snapshot for edits. Call get_object with format: "structured" before updating metadata, properties, collections, blocks, or deleting content. Keep the relevant IDs and subtree.
7. Use concurrency-safe object operations. Same-object reads may run concurrently; mutations use an exclusive object lock and wait for active reads or other writes, while different objects proceed concurrently. Do not replay a multi-stage create blindly after a timeout, rate limit, or partial failure.
8. Interpret verification. Synchronous mutation responses include readback verification. Check both the response envelope and verification; do not equate transport success with confirmed persistence.
9. Confirm the result. When precision matters, or verification is disabled, mismatched, or failed, call get_object again and compare the requested fields or block subtree with the before snapshot. For deletion, verify not-found as documented.
10. Report honestly. State what changed, whether readback verified it, and any loss, warning, recoverable object ID, or unresolved ambiguity.