style: codestyle for mcp stdio instrumentor

.secrets.baseline

@@ -137,7 +137,7 @@
         "filename": "src/starbridge/hello/service.py",
         "hashed_secret": "b96ff7d04dbdf5211aa6bf8ac3a557f30dc7469b",
         "is_verified": false,
-        "line_number": 115,
+        "line_number": 179,
         "is_secret": false
       }
     ],
@@ -152,5 +152,5 @@
       }
     ]
   },
-  "generated_at": "2025-01-04T15:27:01Z"
+  "generated_at": "2025-01-05T13:31:54Z"
 }

pyproject.toml

@@ -120,7 +120,7 @@ dev = [
     "pytest-docker>=3.1.1",
     "pytest-env>=1.1.5",
     "pytest-xdist[psutil]>=3.6.1",
-    "ruff>=0.8.5",
+    "ruff>=0.8.6",
     "sphinx>=8.1.3",
     "sphinx-autobuild>=2024.10.3",
     "sphinx-copybutton>=0.5.2",
@@ -142,7 +142,7 @@ target-version = "py311"
 preview = true
 fix = true
 line-length = 120
-exclude = [".fixme", "src/starbridge/instrumentation/*"]
+exclude = [".fixme"]
 
 
 [tool.ruff.lint]
@@ -198,6 +198,8 @@ ignore = [
 [tool.ruff.format]
 docstring-code-format = true
 
+[tool.ruff.lint.pydocstyle]
+convention = "google"
 
 [tool.pytest.ini_options]
 addopts = "-v --cov=starbridge --cov-report=term-missing --cov-report=xml:coverage.xml --cov-report=html:coverage_html"

src/starbridge/claude/cli.py

@@ -62,7 +62,15 @@ def log(
             ),
         ] = __project_name__,
     ) -> None:
-        """Show logs."""
+        """
+        Show logs.
+
+        Args:
+            tail: Tail logs
+            last: Number of lines to show
+            name: Name of the MCP server - use 'main' for main mcp.log of Claude Desktop application
+
+        """
         log_path = Service.log_path(name if name != "main" else None)
         size = pathlib.Path(log_path).stat().st_size
         human_size = f"{size / 1024 / 1024:.1f}MB" if size > 1024 * 1024 else f"{size / 1024:.1f}KB"

src/starbridge/claude/service.py

@@ -28,6 +28,9 @@ def health(self, context: MCPContext | None = None) -> Health:  # noqa: ARG002
         """
         Check if Claude Desktop application is installed and is running.
 
+        Args:
+            context (MCPContext | None): Optional MCP context.
+
         Returns:
             Health: Health status of the Claude Desktop application.
 
@@ -50,6 +53,9 @@ def info(self, context: MCPContext | None = None):  # noqa: ARG002, ANN201
 
         This includes if it is installed, running, config, and processes running next to Claude.
 
+        Args:
+            context (MCPContext | None): Optional MCP context.
+
         Returns:
             dict: Information about the Claude Desktop application.
 
@@ -93,6 +99,9 @@ def restart(self, context: MCPContext | None = None) -> str:  # noqa: PLR6301, A
 
         The agent should use this tool when asked to restart itself.
 
+        Args:
+            context (MCPContext | None): Optional MCP context.
+
         Returns:
             str: Confirmation message.
 
@@ -198,6 +207,9 @@ def config_write(config: dict) -> dict:
         """
         Write config to file.
 
+        Args:
+            config (dict): Configuration data to write.
+
         Returns:
             dict: Written configuration data.
 
@@ -234,6 +246,9 @@ def log_path(mcp_server_name: str | None = __project_name__) -> Path:
         """
         Get path of MCP server log file.
 
+        Args:
+            mcp_server_name (str | None): Name of the MCP server. Defaults to project name.
+
         Returns:
             Path: Log file path.
 
@@ -252,6 +267,11 @@ def install_mcp_server(
         """
         Install MCP server in Claude Desktop application.
 
+        Args:
+            mcp_server_config (dict): Configuration for the MCP server.
+            mcp_server_name (str): Name of the MCP server.
+            restart (bool): Restart Claude Desktop application after installation.
+
         Returns:
             bool: True if installation successful.
 
@@ -288,6 +308,10 @@ def uninstall_mcp_server(
         """
         Uninstall MCP server from Claude Desktop application.
 
+        Args:
+            mcp_server_name (str): Name of the MCP server.
+            restart (bool): Restart Claude Desktop application after uninstallation.
+
         Returns:
             bool: True if uninstallation successful.
 

src/starbridge/cli.py

@@ -63,7 +63,19 @@ def main(
         ),
     ] = None,
 ) -> None:
-    """Run MCP Server - alias for 'mcp serve'."""
+    """
+    Run MCP Server - alias for 'mcp serve'.
+
+    Args:
+        ctx (typer.Context): Typer context
+        host (str): Host to run the server on
+        port (int): Port to run the server on
+        debug (bool): Debug mode
+        env (list[str]): Environment variables in key=value format. Can be used multiple times in one call.
+            Only STARBRIDGE_ prefixed vars are used. Example --env
+            'STARBRIDGE_ATLASSIAN_URL="https://your-domain.atlassian.net" --env STARBRIDGE_ATLASSIAN_EMAIL="YOUR_EMAIL"'
+
+    """
     # --env parsed in main __init__.py
     if ctx.invoked_subcommand is None:
         MCPServer.serve(host, port, debug)
@@ -126,6 +138,11 @@ def install(
     Install starbridge within Claude Desktop application.
 
     Adds starbridge configuration and restarts Claude Desktop app.
+
+    Args:
+        restart_claude (bool): Restart Claude Desktop application post installation
+        image (str): Docker image to use for Starbridge. Only applies if started as container
+
     """
     if ClaudeService.install_mcp_server(
         generate_mcp_server_config(prompt_for_env(), image),
@@ -153,6 +170,10 @@ def uninstall(
     Uninstall starbridge from Claude Desktop application.
 
     Removes starbridge configuration and restarts Claude Desktop app.
+
+    Args:
+        restart_claude (bool): Restart Claude Desktop application post installation
+
     """
     if ClaudeService.uninstall_mcp_server(restart=restart_claude):
         console.print("Starbridge uninstalled from Claude Destkop application.")

src/starbridge/confluence/cli.py

@@ -71,7 +71,13 @@ def prompts() -> None:
 def prompt_space_summary(
     style: Annotated[str, typer.Option(help="Style of summary")] = "brief",
 ) -> None:
-    """Prompt to generate summary of spaces."""
+    """
+    Prompt to generate summary of spaces.
+
+    Args:
+        style (str): Style of summary
+
+    """
     console.print(Service().space_summary(style))
 
 
@@ -101,7 +107,13 @@ def page() -> None:
 
 @cli_page.command(name="list")
 def page_list(space_key: str = typer.Option(..., help="Space key")) -> None:
-    """List pages in a space."""
+    """
+    List pages in a space.
+
+    Args:
+        space_key (str): Key of the space to list pages from
+
+    """
     console.print(Service().page_list(space_key))
 
 
@@ -112,7 +124,16 @@ def page_create(
     body: str = typer.Option(..., help="Body of the page"),
     page_id: str = typer.Option(None, help="Parent page id"),
 ) -> None:
-    """Create a new page."""
+    """
+    Create a new page.
+
+    Args:
+        space_key (str): Key of the space to create the page in
+        title (str): Title of the page
+        body (str): Body of the page
+        page_id (str): Parent page
+
+    """
     console.print(Service().page_create(space_key, title, body, page_id))
 
 
@@ -130,11 +151,25 @@ def page_update(
     title: str = typer.Option(..., help="Title of the page"),
     body: str = typer.Option(..., help="Body of the page"),
 ) -> None:
-    """Update a page."""
+    """
+    Update a page.
+
+    Args:
+        page_id (str): Page id
+        title (str): Title of the page
+        body (str): Body of the page
+
+    """
     console.print(Service().page_update(page_id, title, body))
 
 
 @cli_page.command(name="delete")
 def page_delete(page_id: str = typer.Option(..., help="Pager id")) -> None:
-    """Delete a page."""
+    """
+    Delete a page.
+
+    Args:
+        page_id (str): Page id
+
+    """
     console.print(Service().page_delete(page_id))

src/starbridge/hello/cli.py

@@ -33,7 +33,13 @@ def info() -> None:
 
 @cli.command()
 def hello(locale: Annotated[str, typer.Option(help="Locale to use")] = "en_US") -> None:
-    """Print Hello World."""
+    """
+    Print Hello World.
+
+    Args:
+        locale (str): Locale to use
+
+    """
     console.print(Service().hello(locale))
 
 
@@ -49,7 +55,14 @@ def bridge(
             ),
         ] = False,
     ) -> None:
-        """Show image of starbridge."""
+        """
+        Show image of starbridge.
+
+        Args:
+            dump (bool): If set, will dump to file starbridge.png in current working directory.
+                Defaults to opening viewer to show the image.
+
+        """
         try:
             image = Service().bridge()
             if dump:
@@ -84,7 +97,14 @@ def pdf(
         ),
     ] = False,
 ) -> None:
-    """Show pdf of starbridge."""
+    """
+    Show pdf of starbridge.
+
+    Args:
+        dump (bool): If set, will dump to file starbridge.pdf in current working directory.
+            Defaults to opening viewer to show the document.
+
+    """
     pdf = Service().pdf_bytes()
 
     if dump:

src/starbridge/hello/service.py

@@ -22,6 +22,9 @@ def health(self, context: MCPContext | None = None) -> Health:  # noqa: ARG002,
         """
         Check health of Hello World service.
 
+        Args:
+            context (MCPContext | None): Optional MCP context.
+
         Returns:
             Health: The health status of the service.
 
@@ -33,6 +36,9 @@ def info(self, context: MCPContext | None = None) -> dict:  # noqa: ARG002, PLR6
         """
         Info about Hello world environment.
 
+        Args:
+            context (MCPContext | None): Optional MCP context.
+
         Returns:
             dict: Information about the Hello World service environment.
 
@@ -45,8 +51,8 @@ def hello(self, locale: str = "en_US", context: MCPContext | None = None) -> str
         Print hello world in different languages.
 
         Args:
-            locale: Language/region code to use for the greeting.
-            context: Optional MCP context.
+            locale (str): Language/region code to use for the greeting.
+            context (MCPContext | None): Optional MCP context.
 
         Returns:
             str: The greeting message in the specified language.
@@ -71,11 +77,14 @@ def bridge(self, context: MCPContext | None = None):  # noqa: ARG002, ANN201, PL
             """
             Show image of starbridge.
 
+            Args:
+                context (MCPContext | None): Optional MCP context.
+
             Returns:
                 PIL.Image.Image: Image object containing the starbridge logo
 
             """
-            import cairosvg  # noqa: PLC0415
+            import cairosvg  # type: ignore # noqa: PLC0415
             from PIL import Image  # noqa: PLC0415
 
             return Image.open(
@@ -89,6 +98,9 @@ def pdf(self, context: MCPContext | None = None) -> EmbeddedResource:  # noqa: A
         """
         Show pdf document with Hello World.
 
+        Args:
+            context (MCPContext | None): Optional MCP context.
+
         Returns:
             EmbeddedResource: A PDF document containing Hello World
 
@@ -107,6 +119,9 @@ def pdf_bytes(context: MCPContext | None = None) -> bytes:  # noqa: ARG004
         """
         Show pdf document with Hello World.
 
+        Args:
+            context (MCPContext | None): Optional MCP context.
+
         Returns:
             bytes: PDF document containing Hello World as bytes