MCP Server API

Overview

Model Context Protocol server for AST-rendered DITA documentation, exposed over the Streamable HTTP transport (--transport http). The stdio transport has no HTTP surface.

All MCP traffic is JSON-RPC 2.0 on a single endpoint, /mcp. A client opens a session with an initialize request (no session header); the response carries an Mcp-Session-Id header that must accompany every later request. Idle sessions are reaped after 30 minutes.

Tools

ToolArgumentsPurpose
list_documentation_setsnoneList doc sets with titles, descriptions and topic counts
get_tocdocIdHierarchical table of contents for a doc set
search_documentationquery, docId?, lang?Ranked topic matches; delegates to the RAG service when RAG_SERVICE_URL is set, otherwise MiniSearch
get_topic_contentdocId, topicPathFull topic as Markdown
render_topic_uidocId, topicPath, theme?Interactive MCP-UI rendering of a topic

Resources: docs://library (JSON catalog), docs://summary (plain-text summary) and ui://dita-docs/topic-viewer.html (the viewer app shell).

Version information

Version: 1.0.0

URI scheme

Host: {scheme}://{host}:{port}

MCP Server - Transport

Streamable HTTP transport carrying MCP JSON-RPC traffic

Parameters

TypeNameDescriptionSchema
Header

Mcp-Session-Id
required

 string (uuid)

Responses

HTTP CodeDescriptionSchema
200 Server-sent event stream for the session string
400 Invalid or missing session ID string

Produces

  • text/event-stream
  • text/plain

Send initialize without a session header to start a session, then include Mcp-Session-Id on every request (tools/list, tools/call, resources/read, ...). Depending on the request, the reply is a single JSON body or a text/event-stream.

Parameters

TypeNameDescriptionSchema
Header

Mcp-Session-Id
optional

 Omit only on the initialize request string (uuid)
Body

body
required

 JsonRpcRequest

Responses

HTTP CodeDescriptionSchema
200

JSON-RPC response, as JSON or a server-sent event stream
Headers: Mcp-Session-Id (string)

 object
400 No valid session ID, and the request was not initialize JsonRpcError
500 Internal server error JsonRpcError

Produces

  • application/json
  • text/event-stream

Parameters

TypeNameDescriptionSchema
Header

Mcp-Session-Id
required

 string (uuid)

Responses

HTTP CodeDescriptionSchema
200 Session closed No Content
400 Invalid or missing session ID string

Produces

  • text/plain

MCP Server - Viewer

HTML app shell for rendering topics in MCP-UI clients

HTML shell used by MCP-UI clients to render render_topic_ui output, also embeddable in an iframe.

Responses

HTTP CodeDescriptionSchema
200 Viewer HTML string

Produces

  • text/html

Definitions

NameDescriptionSchema

jsonrpc
required

 string

id
optional

 Omitted for notifications object

method
required


Example: tools/list

 string

params
optional

 object

NameDescriptionSchema

jsonrpc
optional


Example: 2.0

 string

error
optional

 object

id
optional

 integer