Python MCP Servers

uv init docs-assistant --python 3.12
cd docs-assistant
uv add "mcp[cli]==2.2.*"

"""Stubbed in-memory documentation index shared by the docs-assistant examples."""
from dataclasses import dataclass


@dataclass(frozen=True)
class Page:
    component: str
    page: str
    title: str
    text: str


PAGES = [
    Page("algebra", "matrices", "Matrices", "Matrix decompositions such as LU, QR and SVD solve linear systems."),
    Page("algebra", "wrappers", "Wrappers", "Wrapper classes hide the decomposition details behind a simple solver."),
    Page("units", "conversion", "Unit conversion", "Convert lengths, masses and times between unit systems."),
    Page("statistics", "gaussian", "Gaussian distributions", "Normal distributions, means and covariance matrices."),
]

COMPONENTS = sorted({p.component for p in PAGES})


def search(query: str, component: str, top_k: int = 3) -> list[dict]:
    words = {w.lower() for w in query.split()}
    hits = []
    for p in PAGES:
        if p.component != component:
            continue
        haystack = f"{p.title} {p.text}".lower()
        score = sum(1 for w in words if w in haystack)
        if score:
            hits.append({"component": p.component, "page": p.page, "title": p.title,
                         "score": score, "snippet": p.text})
    hits.sort(key=lambda h: (-h["score"], h["page"]))
    return hits[:top_k]


def read(component: str, page: str) -> str:
    for p in PAGES:
        if p.component == component and p.page == page:
            return f"= {p.title}\n\n{p.text}\n"
    raise KeyError(f"unknown page {component}/{page}")

"""docs-assistant MCP server, Python (mcp v2 MCPServer). Stdio or Streamable HTTP."""
import sys
from typing import Annotated, Literal

from pydantic import BaseModel, Field

from mcp.server import MCPServer
from mcp.server.mcpserver import Elicit, Resolve
from mcp.types import ToolAnnotations

import store

mcp = MCPServer("docs-assistant", version="1.0.0")


class Hit(BaseModel):
    component: str
    page: str
    title: str
    score: int
    snippet: str


class SearchResult(BaseModel):
    query: str
    component: str
    hits: list[Hit]


class ComponentChoice(BaseModel):
    component: Literal["algebra", "units", "statistics"] = Field(description="Which component to search")


async def choose_component(component: str | None) -> ComponentChoice | Elicit[ComponentChoice]:
    if component:
        return ComponentChoice(component=component)  # type: ignore[arg-type]
    return Elicit("Which component should I search?", ComponentChoice)


@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=False))
async def search_docs(
    query: str,
    choice: Annotated[ComponentChoice, Resolve(choose_component)],
    component: str | None = None,
    top_k: int = 3,
) -> SearchResult:
    """Search the documentation of one component and return the best matching pages."""
    hits = store.search(query, choice.component, top_k)
    return SearchResult(query=query, component=choice.component, hits=[Hit(**h) for h in hits])


@mcp.resource("docs://{component}/{page}", mime_type="text/asciidoc")
def read_page(component: str, page: str) -> str:
    """The AsciiDoc source of one documentation page."""
    return store.read(component, page)


@mcp.prompt()
def answer_with_citations(question: str, component: str = "algebra") -> str:
    """Instruct the model to answer from the docs and cite page URIs."""
    return (f"Answer the question using only search_docs results for component '{component}'. "
            f"Cite every claim as docs://{component}/<page>.\n\nQuestion: {question}")


if __name__ == "__main__":
    transport = sys.argv[1] if len(sys.argv) > 1 else "stdio"
    mcp.run(transport)  # "stdio" or "streamable-http"

"""docs-assistant with the standalone FastMCP 4 (PrefectHQ): same tool, resource template and prompt."""
from fastmcp import FastMCP
from pydantic import BaseModel

import store

mcp = FastMCP("docs-assistant", version="1.0.0")


class Hit(BaseModel):
    component: str
    page: str
    title: str
    score: int
    snippet: str


class SearchResult(BaseModel):
    query: str
    component: str
    hits: list[Hit]


@mcp.tool(annotations={"readOnlyHint": True, "openWorldHint": False})
def search_docs(query: str, component: str, top_k: int = 3) -> SearchResult:
    """Search the documentation of one component and return the best matching pages."""
    if component not in store.COMPONENTS:
        raise ValueError(f"Unknown component '{component}'")
    return SearchResult(query=query, component=component,
                        hits=[Hit(**h) for h in store.search(query, component, top_k)])


@mcp.resource("docs://{component}/{page}", mime_type="text/asciidoc")
def read_page(component: str, page: str) -> str:
    """The AsciiDoc source of one documentation page."""
    return store.read(component, page)


@mcp.prompt
def answer_with_citations(question: str, component: str = "algebra") -> str:
    """Instruct the model to answer from the docs and cite page URIs."""
    return (f"Answer the question using only search_docs results for component '{component}'. "
            f"Cite every claim as docs://{component}/<page>.\n\nQuestion: {question}")


if __name__ == "__main__":
    mcp.run()                              # stdio; mcp.run(transport="http", port=8000) serves /mcp