updated doc strings

docforge/servers/__init__.py

@@ -1,5 +1,13 @@
+"""
+Server layer for doc-forge.
+
+This module exposes server implementations used to provide live access
+to generated documentation resources. Currently, it includes the MCP
+documentation server.
+"""
+
 from .mcp_server import MCPServer
 
 __all__ = [
     "MCPServer",
-]
+]

docforge/servers/mcp_server.py

@@ -9,16 +9,21 @@ from mcp.server.fastmcp import FastMCP
 
 class MCPServer:
     """
-    MCP server for serving a pre-built MCP documentation bundle.
+    MCP server for serving a pre-generated documentation bundle.
+
+    The server exposes documentation resources and diagnostic tools through
+    MCP endpoints backed by JSON files generated by the MCP renderer.
     """
 
     def __init__(self, mcp_root: Path, name: str) -> None:
         """
-        Initialize the MCPServer.
+        Initialize the MCP server.
 
         Args:
-            mcp_root: Path to the directory containing pre-built MCP JSON resources.
-            name: Name of the MCP server.
+            mcp_root: Directory containing the generated MCP documentation
+                bundle (for example ``index.json``, ``nav.json``, and
+                ``modules/``).
+            name: Identifier used for the MCP server instance.
         """
         self.mcp_root = mcp_root
         self.app = FastMCP(name)
@@ -32,19 +37,24 @@ class MCPServer:
 
     def _read_json(self, path: Path) -> Any:
         """
-        Read and parse a JSON file, returning diagnostic errors if missing.
+        Load and parse a JSON file.
+
+        If the file does not exist, a structured error response is returned
+        instead of raising an exception.
 
         Args:
-            path: Path to the JSON file.
+            path: Path to the JSON file to read.
 
         Returns:
-            The parsed JSON data or an error dictionary.
+            Parsed JSON data if the file exists, otherwise an error dictionary
+            describing the missing resource.
         """
         if not path.exists():
             return {
                 "error": "not_found",
                 "path": str(path),
             }
+
         return json.loads(path.read_text(encoding="utf-8"))
 
     # ------------------------------------------------------------------
@@ -53,8 +63,16 @@ class MCPServer:
 
     def _register_resources(self) -> None:
         """
-        Register MCP resources for index, nav, and individual modules.
+        Register MCP resource endpoints.
+
+        The server exposes documentation resources through the following
+        endpoints:
+
+        - ``docs://index`` – Project metadata
+        - ``docs://nav`` – Navigation structure
+        - ``docs://modules/{module}`` – Individual module documentation
         """
+
         @self.app.resource("docs://index")
         def index():
             return self._read_json(self.mcp_root / "index.json")
@@ -70,26 +88,35 @@ class MCPServer:
             )
 
     # ------------------------------------------------------------------
-    # MCP tools (optional / diagnostic)
+    # MCP tools
     # ------------------------------------------------------------------
 
     def _register_tools(self) -> None:
         """
-        Register high-level MCP tools for diagnostics.
+        Register optional MCP diagnostic tools.
+
+        These tools provide lightweight endpoints useful for verifying that
+        the MCP server is operational.
         """
+
         @self.app.tool()
         def ping() -> str:
+            """Return a simple health check response."""
             return "pong"
 
     # ------------------------------------------------------------------
     # Server lifecycle
     # ------------------------------------------------------------------
 
-    def run(self, transport: Literal["stdio", "sse", "streamable-http"] = "streamable-http") -> None:
+    def run(
+        self,
+        transport: Literal["stdio", "sse", "streamable-http"] = "streamable-http",
+    ) -> None:
         """
         Start the MCP server.
 
         Args:
-            transport: MCP transport (default: streamable-http)
+            transport: Transport mechanism used by the MCP server. Supported
+                options include ``stdio``, ``sse``, and ``streamable-http``.
         """
         self.app.run(transport=transport)