Add MCP/legacy API guide; document multiple inheritance and createPage pitfall

[ChipNowacek]

Summary

Three additions from live testing against a Logseq DB graph (2026-03-07):

• New file: skill/references/catalyst-query-protocol.md — Guide for accessing Logseq from external tools (MCP transport + legacy HTTP API), including working Python helpers
• core-apis.md — Confirmed :logseq.property.class/extends is cardinality-many; documented multiple inheritance behavior
• pitfalls-and-solutions.md — New pitfall: createPage with tags:[] does not apply class tags

Detail

New: External tool access guide (catalyst-query-protocol.md)

Covers two access paths for external clients (scripts, Claude Code, etc.):

MCP Streamable HTTP (protocol version 2024-11-05)

• POST /mcp for tool calls; session ID in mcp-session-id response header
• initialize response body is intentionally empty — session ID is in the header only
• Tool call responses arrive as chunked SSE in the POST response body (event: message\ndata: {...})
• urllib.request.urlopen().read() blocks forever on chunked SSE — working raw-socket Python helpers included
• Known bug: new MCP sessions return HTTP 200 with empty body for all tool calls; graph must be open and active; reuse the session ID from the session established when the graph first loaded

Legacy HTTP API at /api (port 12315)

• Accepts {"method": "logseq.Editor.methodName", "args": [...]} synchronously
• Bearer token auth; returns JSON directly (no SSE)
• Right path for mutations external clients need: createTag, addTagExtends, addTagProperty, addBlockTag, deletePage, getTagObjects, etc.
• Note: logseq.api.* namespace is not exposed — use logseq.Editor.*

Updated: Multiple inheritance (core-apis.md)

Confirmed :logseq.property.class/extends is cardinality-many:

• addTagExtends(child, parentA) then addTagExtends(child, parentB) stores two separate datoms — both parents retained, neither overwrites the other
• The standard or-join Datalog pattern handles multi-parent classes without modification
• getTagObjects is hierarchy-aware and traverses extends

Updated: createPage class tag pitfall (pitfalls-and-solutions.md)

createPage('Name', { tags: ['ClassName'] }) does not apply the class tag — the page receives only the default Page tag. Workaround: call addBlockTag(uuid, 'ClassName') explicitly after page creation.

Test plan

• Verify Python MCP helpers connect and execute a tool call against a running Logseq instance
• Verify legacy API helper can call logseq.Editor.createTag
• Confirm multiple inheritance Datalog queries return correct results with two parents
• Confirm createPage + addBlockTag correctly applies class tag

🤖 Generated with Claude Code