MCP Server Service mcp-server

Model Context Protocol (MCP) server providing OASIS metadata, clean Markdown text context, search, and MCP-UI interactive component rendering to AI assistants.

Service Overview

The mcp-server service operates on port 4001 (HTTP transport) or via standard I/O (stdio transport). It connects AI models to published DITA documentation sets.

Exposed MCP Tools

list_documentation_sets
Discovers available documentation sets and returns OASIS metadata (title, description, keywords, category, lang).
get_toc
Returns the hierarchical Table of Contents structure for a document set.
search_documentation
Executes documentation search queries. Transparently delegates to rag-service if configured, with automatic fallback to MiniSearch keyword search.
get_topic_content
Converts topic AST JSON trees into clean Markdown text for LLM reasoning and question-answering.
render_topic_ui
MCP-UI Tool returning a self-contained HTML/CSS frame rendering interactive React components directly inside chat windows.

Search Delegation & Fallback Architecture

When the search_documentation tool is called, mcp-server evaluates its configured search providers:

  • Semantic RAG Search: If RAG_SERVICE_URL is set (e.g. http://rag-service:4002), queries are sent to the standalone vector search service.
  • Keyword Search Fallback: If rag-service is unconfigured, unreachable, or returns empty results, queries automatically fall back to local MiniSearch indices without disrupting chat flow.

Container Deployment & Configuration

Deploy using Docker Compose or a standalone Docker container:

# Launch using Docker Compose:
docker compose up -d mcp-server

# Or run as a standalone Docker container:
docker run -d -p 4001:4001 \
  -v /path/to/data:/app/data \
  -e RAG_SERVICE_URL=http://rag-service:4002 \
  ghcr.io/jason-fox/ast-mcp-server:latest

Configuration Parameters:

PORT
HTTP port for Streamable HTTP transport (default: 4001).
RAG_SERVICE_URL
Optional URL of the standalone RAG vector search service (e.g. http://<rag-service>, where <rag-service> is the host and port the service is running on, e.g. localhost:4002).
BOOTSTRAP_THEME
Bootswatch theme name used for render_topic_ui frames (default: default).