feat: expose knowledge-base documentation through an MCP server #117

Feature Description

Provide an MCP server for the knowledge base so AI agents and other MCP-compatible clients can discover documentation and retrieve relevant documents without scraping rendered HTML.

The server should expose the documentation catalog as MCP Resources and provide agent-friendly discovery/search operations:

• List available documentation, with stable identifiers, title, app, description, tags, route, MIME type, and modification metadata.
• Search documentation by keyword and return ranked, bounded matches with excerpts and canonical document resource URIs.
• Allow clients to fetch a selected document through resources/read.

Problem / Opportunity

The knowledge base aggregates documentation into a browser-oriented static site. Agentic clients need a protocol-native, structured interface for retrieval-augmented workflows: first discover/search available material, then fetch only relevant content.

A standard MCP surface makes this capability pluggable across compatible agents and clients, rather than coupling consumers to one UI, scraper, or proprietary API.

Acceptance Criteria

• An MCP server can be run/configured against a built knowledge-base deployment or its generated documentation index.
• Server advertises MCP resources and tools capabilities.
• resources/list exposes a deterministic, paginated document catalog using stable kb:// URIs.
• resources/read returns requested document content and metadata for a catalog URI.
• A list_documents tool supports filtered catalog discovery (for example app, tag, or title).
• A search_documents tool accepts a keyword query and optional filters, pagination, and result limit.
• Search results return deterministic ranking plus structured metadata: document URI, title, app/slug, route, excerpt, and relevance score.
• Tool outputs use JSON Schemas and return schema-valid structured content, with compatible text content where needed.
• Search and document reads enforce bounded response sizes and clear errors for unknown or inaccessible resources.
• Build/deployment produces required search/catalog data without runtime HTML scraping.
• Server validates inputs, applies access controls appropriate to deployment, rate-limits requests, and sanitizes returned content.
• Automated tests cover resource listing/reading, search ranking/filtering/pagination, schemas, deterministic ordering, and error handling.
• Documentation explains supported transport/configuration, MCP client setup, URI format, tool schemas, and security/operational limits.

Proposed Solution

Generate a normalized document catalog and search index during the existing static build pipeline. Implement a separate MCP adapter over that generated data so retrieval behavior stays independent from browser rendering and can be deployed or embedded using a supported MCP transport.

Use two complementary MCP primitives:

1. Resources for canonical documents. Each document receives a stable kb:// URI, appears in resources/list, and is retrieved through resources/read.
2. Tools for agent-directed discovery:
   • list_documents for filtered catalog enumeration.
   • search_documents for ranked keyword search.

Search responses should return compact structured matches and resource links, enabling an agent to request full content only after selecting relevant results. Keep tool names server-namespaced and output schemas explicit to support aggregation with other MCP servers.

Evaluate whether resource-list change notifications should be enabled for deployments where documentation updates without server restart.

Dependencies / Related

• MCP Resources specification: https://modelcontextprotocol.io/specification/2026-07-28/server/resources
• MCP Tools specification: https://modelcontextprotocol.io/specification/2026-07-28/server/tools
• MCP architecture overview: https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture

No existing MCP-related issue found in this repository.

Additional Context

Research findings:

• MCP Resources fit canonical documentation: clients can list resources, select them explicitly or automatically, and retrieve content by URI.
• MCP Tools fit parameterized search because keyword input, filters, ranking, and bounded result sets are actions rather than static documents.
• MCP requires deterministic list order and supports pagination/caching, useful for large documentation catalogs and agent prompt caching.
• Tool output schemas improve interoperability; structured search matches should be paired with readable text output for broad client compatibility.
• MCP security guidance requires input validation, access control, rate limiting, output sanitization, and client-side validation of untrusted tool results.