doc-forge/docs/mcp/modules/docforge.cli.mcp_utils.json

{
  "module": "docforge.cli.mcp_utils",
  "content": {
    "path": "docforge.cli.mcp_utils",
    "docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.\n\n---\n\nNotes:\n    - `generate_resources` produces the bundle consumed by `MCPServer`:\n      `index.json`, `nav.json`, and per-module resources under `modules/`.\n    - Resource URIs use the `docs://` scheme: `docs://index`, `docs://nav`,\n      and `docs://modules/{module}`.\n\n---",
    "objects": {
      "GriffeLoader": {
        "name": "GriffeLoader",
        "kind": "class",
        "path": "docforge.cli.mcp_utils.GriffeLoader",
        "signature": "GriffeLoader()",
        "docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.\n\nAttributes:\n    _loader (_GriffeLoader):\n        Internal Griffe loader with dedicated module and line collections.",
        "members": {
          "load_project": {
            "name": "load_project",
            "kind": "function",
            "path": "docforge.cli.mcp_utils.GriffeLoader.load_project",
            "signature": "load_project(module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None)",
            "docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n    module_paths (list[str]):\n        List of dotted module import paths to load.\n\n    project_name (str | None):\n        Optional override for the project name. Defaults to the top-level\n        name of the first module.\n\n    skip_import_errors (bool | None):\n        If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n    Project:\n        A populated `Project` instance containing the loaded modules.\n\nRaises:\n    ValueError:\n        If no module paths are provided.\n\n    ImportError:\n        If a module fails to load and `skip_import_errors` is False."
          },
          "load_module": {
            "name": "load_module",
            "kind": "function",
            "path": "docforge.cli.mcp_utils.GriffeLoader.load_module",
            "signature": "load_module(path: str)",
            "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n    path (str):\n        Dotted import path of the module.\n\nReturns:\n    Module:\n        A populated `Module` instance.\n\nRaises:\n    ImportError:\n        If the module cannot be loaded by Griffe.\n\n    KeyError:\n        If the loaded module is missing from the module collection.\n\nExample:\n    Load a single module:\n\n        ```python\n        loader = GriffeLoader()\n        module = loader.load_module(\"mypackage.submodule\")\n        ```"
          }
        }
      },
      "discover_module_paths": {
        "name": "discover_module_paths",
        "kind": "function",
        "path": "docforge.cli.mcp_utils.discover_module_paths",
        "signature": "discover_module_paths(module_name: str, project_root: Path | None = None)",
        "docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n    module_name (str):\n        Top-level package name to discover modules from.\n\n    project_root (Path | None):\n        Root directory used to resolve module paths. If not provided, the\n        current working directory is used.\n\nReturns:\n    list[str]:\n        A sorted list of unique dotted module import paths.\n\nRaises:\n    FileNotFoundError:\n        If the specified package directory does not exist."
      },
      "MCPRenderer": {
        "name": "MCPRenderer",
        "kind": "class",
        "path": "docforge.cli.mcp_utils.MCPRenderer",
        "signature": null,
        "docstring": "Renderer that generates MCP-compatible documentation resources.\n\nThis renderer converts doc-forge project models into structured JSON\nresources suitable for consumption by systems implementing the Model\nContext Protocol (MCP).",
        "members": {
          "name": {
            "name": "name",
            "kind": "attribute",
            "path": "docforge.cli.mcp_utils.MCPRenderer.name",
            "signature": null,
            "docstring": null
          },
          "generate_sources": {
            "name": "generate_sources",
            "kind": "function",
            "path": "docforge.cli.mcp_utils.MCPRenderer.generate_sources",
            "signature": "generate_sources(project: Project, out_dir: Path)",
            "docstring": "Generate MCP documentation resources for a project.\n\nThe renderer serializes each module into a JSON resource and produces\nsupporting metadata files such as `nav.json` and `index.json`.\n\nArgs:\n    project (Project):\n        Documentation project model to render.\n\n    out_dir (Path):\n        Directory where MCP resources will be written."
          }
        }
      },
      "MCPServer": {
        "name": "MCPServer",
        "kind": "class",
        "path": "docforge.cli.mcp_utils.MCPServer",
        "signature": "MCPServer(mcp_root: Path, name: str)",
        "docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.\n\nAttributes:\n    mcp_root (Path):\n        Directory containing the generated MCP documentation bundle.\n\n    app (FastMCP):\n        Underlying FastMCP application instance that registers resources\n        and tools.",
        "members": {
          "mcp_root": {
            "name": "mcp_root",
            "kind": "attribute",
            "path": "docforge.cli.mcp_utils.MCPServer.mcp_root",
            "signature": null,
            "docstring": null
          },
          "app": {
            "name": "app",
            "kind": "attribute",
            "path": "docforge.cli.mcp_utils.MCPServer.app",
            "signature": null,
            "docstring": null
          },
          "run": {
            "name": "run",
            "kind": "function",
            "path": "docforge.cli.mcp_utils.MCPServer.run",
            "signature": "run(transport: Literal['stdio', 'sse', 'streamable-http'] = 'streamable-http')",
            "docstring": "Start the MCP server.\n\nArgs:\n    transport (Literal[\"stdio\", \"sse\", \"streamable-http\"]):\n        Transport mechanism used by the MCP server. Supported options\n        include `stdio`, `sse`, and `streamable-http`."
          }
        }
      },
      "generate_resources": {
        "name": "generate_resources",
        "kind": "function",
        "path": "docforge.cli.mcp_utils.generate_resources",
        "signature": "generate_resources(module: str, project_name: str | None, out_dir: Path) -> None",
        "docstring": "Generate MCP documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n    module (str):\n        Python module import path used as the entry point for\n        documentation generation.\n\n    project_name (str | None):\n        Optional override for the project name used in generated\n        documentation metadata.\n\n    out_dir (Path):\n        Directory where MCP resources (index.json, nav.json, and module data)\n        will be written."
      },
      "serve": {
        "name": "serve",
        "kind": "function",
        "path": "docforge.cli.mcp_utils.serve",
        "signature": "serve(module: str, mcp_root: Path) -> None",
        "docstring": "Start an MCP server for a pre-generated documentation bundle.\n\nThe server exposes documentation resources such as project metadata,\nnavigation structure, and module documentation through MCP endpoints.\n\nArgs:\n    module (str):\n        Python module import path used to identify the served\n        documentation instance.\n\n    mcp_root (Path):\n        Path to the directory containing the MCP documentation\n        bundle (index.json, nav.json, and modules/).\n\nRaises:\n    click.ClickException:\n        If the MCP documentation bundle is missing required files or directories."
      }
    }
  }
}