docs-graph

MCP FastMCP 2 deps

Read-only MCP server exposing docs/public/generated-reports/docs-graph-snapshot.json

Source & provenance

This page is generated from the repository MCP server directory mcp/docs-graph/ (source file mcp/docs-graph/server.py).

Usage

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "docs-graph": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "mcp/docs-graph",
        "python",
        "server.py"
      ]
    }
  }
}

Package

Field	Value
Name	mcp-docs-graph
Version	0.1.0
Python	>=3.13

Dependencies

fastmcp>=2wagents

FastMCP Config

{
  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
  "source": {
    "path": "server.py",
    "entrypoint": "mcp"
  },
  "environment": {
    "type": "uv"
  }
}

Server Source

mcp/docs-graph/server.py

"""MCP server: docs-graph.

Read-only access to the generated docs graph snapshot at
`docs/public/generated-reports/docs-graph-snapshot.json`. No tool in this
server mutates the repository.
"""

from __future__ import annotations

import json
from typing import Any

from fastmcp import FastMCP

from wagents.docs_reports import REPORTS_JSON_DIR

mcp = FastMCP("Docs Graph")

_READ_ONLY = {
    "readOnlyHint": True,
    "destructiveHint": False,
    "idempotentHint": True,
    "openWorldHint": False,
}

_SNAPSHOT_PATH = REPORTS_JSON_DIR / "docs-graph-snapshot.json"


def _load_snapshot() -> dict[str, Any]:
    if not _SNAPSHOT_PATH.is_file():
        raise FileNotFoundError(
            "docs-graph-snapshot.json has not been generated yet. "
            "Run `uv run wagents docs generate` in the repo."
        )
    payload = json.loads(_SNAPSHOT_PATH.read_text(encoding="utf-8"))
    if not isinstance(payload, dict):
        raise ValueError("docs-graph-snapshot.json root must be an object")
    return payload


@mcp.tool(annotations=_READ_ONLY)
def docs_graph_snapshot() -> dict[str, Any]:
    """Return the full generated docs graph snapshot JSON payload.

    Includes `latest` metrics (page count, internal links, orphan pages,
    most-linked pages) and historical `history` rows when present.
    Regenerated by `wagents docs generate`.
    """
    return _load_snapshot()


@mcp.tool(annotations=_READ_ONLY)
def docs_graph_latest() -> dict[str, Any]:
    """Return only the `latest` section of the docs graph snapshot."""
    snapshot = _load_snapshot()
    latest = snapshot.get("latest")
    if not isinstance(latest, dict):
        raise ValueError("docs-graph-snapshot.json missing `latest` object")
    return latest


@mcp.tool(annotations=_READ_ONLY)
def docs_graph_history() -> list[dict[str, Any]]:
    """Return the `history` trend rows from the docs graph snapshot."""
    snapshot = _load_snapshot()
    history = snapshot.get("history", [])
    if not isinstance(history, list):
        raise ValueError("docs-graph-snapshot.json `history` must be a list")
    return [row for row in history if isinstance(row, dict)]


if __name__ == "__main__":
    mcp.run()

Resources

MCP OverviewBrowse all MCP documentation in this site.

CLI ReferenceScaffold new MCP servers with wagents.

---

View source on GitHub