gfa-mcp 0.1.0__tar.gz

gfa_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: gfa-mcp
+Version: 0.1.0
+Summary: MCP server wrapping the gfa Python SDK; exposes 14 tools to MCP-aware agents.
+Author: gfa contributors
+License: MIT
+Project-URL: Homepage, https://gitlab.com/kerusu/gfa
+Project-URL: Repository, https://gitlab.com/kerusu/gfa
+Keywords: gfa,git,agent,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: gfa-sdk>=0.1.0
+Requires-Dist: PyYAML>=6
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+
+# gfa-mcp
+
+Model Context Protocol server wrapping the gfa Python SDK.
+
+`gfa-mcp` is a sidecar that exposes 14 gfa primitives as MCP tools so
+off-the-shelf agent platforms (Claude Code, Cursor, Codex Agent, Cline,
+Continue.dev) can call them without bespoke per-platform integration.
+
+The MCP server is a thin adapter — every tool maps 1:1 to an SDK method.
+Routing, caching, and threshold heuristics live in the SDK
+(`gfa-sdk`), not here. See `docs/architecture/sdk-mcp.md` in the gfa
+repo for the full design.
+
+## Install
+
+    pip install gfa-mcp
+
+## Quickstart
+
+    # Stdio (agent platform spawns gfa-mcp as a subprocess)
+    gfa-mcp --stdio --endpoint https://gfa.example.com --token "$GFA_JWT"
+
+    # HTTP (long-running, multiple agents on the same host)
+    gfa-mcp --port 8765 --endpoint https://gfa.example.com --key ~/.gfa/agent.pem
+
+    # Inspect the tool list without running the server
+    gfa-mcp --print-tools
+
+## Claude Code wiring
+
+`~/.claude-code/mcp.json`:
+
+    {
+      "mcpServers": {
+        "gfa": {
+          "command": "gfa-mcp",
+          "args": [
+            "--stdio",
+            "--endpoint", "https://gfa.example.com",
+            "--key", "/home/user/.gfa/agent.pem"
+          ]
+        }
+      }
+    }
+
+Cursor and Codex Agent use a similar shape per their respective docs.
+
+## Auth
+
+`--token JWT` for pre-minted JWTs (simple, doesn't auto-rotate).
+`--key PATH` for ECDSA private keys (auto-rotates short-lived tokens via
+the SDK's `FileKeyTokenProvider`). Use `--key` for any session expected
+to live longer than the JWT's TTL.
+
+## Customer docs
+
+The full agent integration guide — AGENTS.md template, system-prompt
+snippets, per-platform config — is M-055-CUSTOMER-DOCS in the gfa
+project backlog and ships separately from this package.

gfa_mcp-0.1.0/README.md

@@ -0,0 +1,59 @@
+# gfa-mcp
+
+Model Context Protocol server wrapping the gfa Python SDK.
+
+`gfa-mcp` is a sidecar that exposes 14 gfa primitives as MCP tools so
+off-the-shelf agent platforms (Claude Code, Cursor, Codex Agent, Cline,
+Continue.dev) can call them without bespoke per-platform integration.
+
+The MCP server is a thin adapter — every tool maps 1:1 to an SDK method.
+Routing, caching, and threshold heuristics live in the SDK
+(`gfa-sdk`), not here. See `docs/architecture/sdk-mcp.md` in the gfa
+repo for the full design.
+
+## Install
+
+    pip install gfa-mcp
+
+## Quickstart
+
+    # Stdio (agent platform spawns gfa-mcp as a subprocess)
+    gfa-mcp --stdio --endpoint https://gfa.example.com --token "$GFA_JWT"
+
+    # HTTP (long-running, multiple agents on the same host)
+    gfa-mcp --port 8765 --endpoint https://gfa.example.com --key ~/.gfa/agent.pem
+
+    # Inspect the tool list without running the server
+    gfa-mcp --print-tools
+
+## Claude Code wiring
+
+`~/.claude-code/mcp.json`:
+
+    {
+      "mcpServers": {
+        "gfa": {
+          "command": "gfa-mcp",
+          "args": [
+            "--stdio",
+            "--endpoint", "https://gfa.example.com",
+            "--key", "/home/user/.gfa/agent.pem"
+          ]
+        }
+      }
+    }
+
+Cursor and Codex Agent use a similar shape per their respective docs.
+
+## Auth
+
+`--token JWT` for pre-minted JWTs (simple, doesn't auto-rotate).
+`--key PATH` for ECDSA private keys (auto-rotates short-lived tokens via
+the SDK's `FileKeyTokenProvider`). Use `--key` for any session expected
+to live longer than the JWT's TTL.
+
+## Customer docs
+
+The full agent integration guide — AGENTS.md template, system-prompt
+snippets, per-platform config — is M-055-CUSTOMER-DOCS in the gfa
+project backlog and ships separately from this package.

gfa_mcp-0.1.0/gfa_mcp/__init__.py

@@ -0,0 +1,16 @@
+"""gfa-mcp — Model Context Protocol server wrapping the gfa Python SDK.
+
+The MCP server is a thin adapter: every tool maps 1:1 to an SDK method.
+Routing and caching live in the SDK, not here. See
+``design/mcp-server-architecture.md`` in the gfa repo.
+
+Public surface used by tests:
+
+- :class:`gfa_mcp.session.SessionState`
+- :class:`gfa_mcp.dispatcher.Dispatcher`
+- :func:`gfa_mcp.tools_loader.load_tools_toml`
+"""
+
+from gfa_mcp._version import __version__
+
+__all__ = ["__version__"]

gfa_mcp-0.1.0/gfa_mcp/_version.py

@@ -0,0 +1,7 @@
+"""Package version + MCP protocol version pinned at build time."""
+
+__version__ = "0.1.0"
+
+# MCP spec version this server speaks. Pinned per design §11 (Risks) — drift
+# is loud, not silent. Upgrading is a single-file change.
+MCP_PROTOCOL_VERSION = "2025-03-26"

gfa_mcp-0.1.0/gfa_mcp/auth.py

@@ -0,0 +1,69 @@
+"""Auth mode resolution.
+
+Two modes per design §Auth flow:
+
+- **Mode A — pre-configured JWT.** Either a literal JWT string (--token)
+  or a private key path used by the SDK's FileKeyTokenProvider (--key).
+- **Mode B — pass-through.** The MCP layer reads the JWT from each
+  agent-supplied request (HTTP Authorization header or stdio param). Not
+  implemented in v1 transports — we surface a clear error when selected.
+
+This module hands the dispatcher a ready-to-use token or TokenProvider;
+the dispatcher constructs ``gfa.Client`` with whatever it gets.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Union
+
+from gfa import FileKeyTokenProvider, TokenProvider
+
+
+def resolve_auth(
+    *,
+    token: str | None,
+    key: str | None,
+    auth_mode: str = "static",
+    token_ttl_hours: int = 1,
+) -> Union[str, TokenProvider]:
+    """Pick the right auth artifact for ``gfa.Client(token=...)``.
+
+    Args:
+        token: pre-minted JWT string (mutually exclusive with ``key``).
+        key: path to ECDSA private key (mutually exclusive with ``token``).
+        auth_mode: ``static`` (default) or ``pass-through``. The latter is
+            documented but not yet wired through the transports — passing
+            it raises ``NotImplementedError`` so customers see the gap
+            instead of a silent misroute.
+        token_ttl_hours: TTL for minted tokens when ``key`` is set.
+
+    Returns:
+        Either a JWT string (Mode A: --token) or a TokenProvider (Mode A:
+        --key).
+
+    Raises:
+        ValueError: neither or both of token / key supplied.
+        NotImplementedError: pass-through mode selected.
+    """
+    if auth_mode == "pass-through":
+        raise NotImplementedError(
+            "pass-through auth (Mode B) is not yet wired through any transport. "
+            "Use --token or --key for now; per-request token injection lands in "
+            "M-055-MCP-AUTH-PASSTHROUGH (sibling backlog).",
+        )
+    if auth_mode != "static":
+        raise ValueError(
+            f"auth_mode must be 'static' or 'pass-through', got {auth_mode!r}",
+        )
+    if token and key:
+        raise ValueError("--token and --key are mutually exclusive")
+    if not token and not key:
+        raise ValueError("one of --token or --key is required (Mode A)")
+    if token:
+        return token
+    provider = FileKeyTokenProvider(
+        Path(key),  # type: ignore[arg-type]
+        ttl_hours=token_ttl_hours,
+    )
+    return provider

gfa_mcp-0.1.0/gfa_mcp/cli.py

@@ -0,0 +1,239 @@
+"""Command-line entry point.
+
+``gfa-mcp`` is the installed console script; this module's :func:`main`
+is its handler. Argument layering: CLI > env vars (``GFA_MCP_*``) > YAML
+config > defaults.
+
+The CLI is intentionally thin: it parses arguments, builds a Client +
+SessionState + Dispatcher, and hands them to the chosen transport.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from gfa import Client
+
+from gfa_mcp._version import MCP_PROTOCOL_VERSION, __version__
+from gfa_mcp.auth import resolve_auth
+from gfa_mcp.dispatcher import Dispatcher
+from gfa_mcp.log import Logger
+from gfa_mcp.session import SessionState
+from gfa_mcp.tool_schemas import INPUT_SCHEMAS, TOOL_NAMES
+from gfa_mcp.tools_loader import default_tools_toml_path, load_tools_toml
+from gfa_mcp.transport.http import HttpTransport
+from gfa_mcp.transport.stdio import StdioTransport
+from gfa_mcp.transport.unix import UnixTransport
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="gfa-mcp",
+        description="gfa-mcp — Model Context Protocol server wrapping the gfa SDK",
+    )
+
+    # Connection target
+    p.add_argument("--endpoint", help="gfa server URL (e.g. https://gfa.example.com)")
+    p.add_argument("--config", help="YAML config file (overrides individual flags)")
+
+    # Auth
+    p.add_argument("--token", help="Pre-minted JWT (Mode A, simple)")
+    p.add_argument("--key", help="Path to private key (Mode A, auto-mint)")
+    p.add_argument(
+        "--auth",
+        choices=["static", "pass-through"],
+        default="static",
+        help="Auth mode (default: static)",
+    )
+    p.add_argument(
+        "--token-ttl-hours",
+        type=int,
+        default=1,
+        help="TTL for minted tokens when --key is used",
+    )
+
+    # Transport
+    p.add_argument("--stdio", action="store_true", help="Use stdio transport")
+    p.add_argument("--port", type=int, help="Bind HTTP on 127.0.0.1:N")
+    p.add_argument("--socket", help="Bind Unix socket at PATH")
+    p.add_argument(
+        "--bind",
+        default="127.0.0.1",
+        help="Override 127.0.0.1 for HTTP (security: understand before changing)",
+    )
+
+    # Tunables
+    p.add_argument("--blob-cache-mb", type=int, default=0)
+    p.add_argument(
+        "--hint-thresholds",
+        default="10,50,200",
+        help="Comma-separated thresholds for proactive hints",
+    )
+    p.add_argument("--partial-clone-ttl", type=int, default=3600)
+    p.add_argument("--max-partial-clones", type=int, default=10)
+    p.add_argument("--tools-toml", help="Override path to tools.toml")
+
+    # Logging
+    p.add_argument(
+        "--log-level",
+        default=os.environ.get("GFA_MCP_LOG_LEVEL", "INFO"),
+        choices=["DEBUG", "INFO", "WARN", "ERROR"],
+    )
+
+    # Diagnostic
+    p.add_argument("--print-tools", action="store_true",
+                   help="Dump the tool list as JSON and exit")
+    p.add_argument("--version", action="version",
+                   version=f"gfa-mcp {__version__} (MCP {MCP_PROTOCOL_VERSION})")
+    return p
+
+
+def _load_yaml_config(path: str) -> dict[str, Any]:
+    import yaml
+
+    with open(path, "rb") as f:
+        data = yaml.safe_load(f) or {}
+    if not isinstance(data, dict):
+        raise SystemExit(f"--config {path}: must be a YAML mapping")
+    return data
+
+
+def _merge_config(args: argparse.Namespace) -> argparse.Namespace:
+    """Layer env vars + optional YAML config under the CLI args.
+
+    Precedence: CLI > env (``GFA_MCP_<FLAG>``) > YAML > argparse defaults.
+    """
+    # YAML first (lowest priority over CLI/env)
+    if args.config:
+        cfg = _load_yaml_config(args.config)
+        if args.endpoint is None:
+            args.endpoint = cfg.get("endpoint")
+        auth = cfg.get("auth") or {}
+        if args.token is None:
+            args.token = auth.get("token")
+        if args.key is None:
+            args.key = auth.get("key")
+        if "mode" in auth and args.auth == "static":
+            args.auth = auth["mode"]
+        transport = cfg.get("transport") or {}
+        if args.port is None and "port" in transport:
+            args.port = transport["port"]
+        if args.socket is None and "socket" in transport:
+            args.socket = transport["socket"]
+        if "stdio" in transport and not args.stdio:
+            args.stdio = bool(transport["stdio"])
+        cache = cfg.get("cache") or {}
+        if not args.blob_cache_mb and "blob_mb" in cache:
+            args.blob_cache_mb = int(cache["blob_mb"])
+        hints = cfg.get("hints") or {}
+        if "thresholds" in hints and args.hint_thresholds == "10,50,200":
+            args.hint_thresholds = ",".join(str(int(x)) for x in hints["thresholds"])
+        pc = cfg.get("partial_clone") or {}
+        if "ttl_seconds" in pc and args.partial_clone_ttl == 3600:
+            args.partial_clone_ttl = int(pc["ttl_seconds"])
+        log = cfg.get("log") or {}
+        if "level" in log and args.log_level == "INFO":
+            args.log_level = log["level"]
+
+    # Env vars (higher than YAML, lower than CLI which is already set)
+    def _env(name: str) -> str | None:
+        return os.environ.get(name)
+
+    if args.endpoint is None:
+        args.endpoint = _env("GFA_MCP_ENDPOINT")
+    if args.token is None:
+        args.token = _env("GFA_MCP_TOKEN")
+    if args.key is None:
+        args.key = _env("GFA_MCP_KEY")
+    return args
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Build and run a gfa-mcp server. Returns process exit code."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    args = _merge_config(args)
+
+    log = Logger(args.log_level)
+
+    # Tool descriptions are loaded from tools.toml; this also cross-checks
+    # against the schema registry and fails fast if anything's missing.
+    tools_toml_path = args.tools_toml or str(default_tools_toml_path())
+    try:
+        descriptions = load_tools_toml(tools_toml_path)
+    except Exception as e:  # noqa: BLE001
+        log.error("tools.toml load failed", path=tools_toml_path, error=str(e))
+        print(f"gfa-mcp: tools.toml load failed: {e}", file=sys.stderr)
+        return 2
+
+    if args.print_tools:
+        out = [
+            {
+                "name": name,
+                "description": descriptions[name],
+                "inputSchema": INPUT_SCHEMAS[name],
+            }
+            for name in TOOL_NAMES
+        ]
+        print(json.dumps({"tools": out}, indent=2, sort_keys=True))
+        return 0
+
+    if not args.endpoint:
+        print("gfa-mcp: --endpoint is required", file=sys.stderr)
+        return 2
+
+    try:
+        auth = resolve_auth(
+            token=args.token,
+            key=args.key,
+            auth_mode=args.auth,
+            token_ttl_hours=args.token_ttl_hours,
+        )
+    except (ValueError, NotImplementedError) as e:
+        print(f"gfa-mcp: auth resolution failed: {e}", file=sys.stderr)
+        return 2
+
+    client = Client(endpoint=args.endpoint, token=auth)
+
+    hint_thresholds = tuple(
+        int(x) for x in str(args.hint_thresholds).split(",") if x.strip()
+    )
+
+    session = SessionState(
+        client=client,
+        log=log,
+        hint_thresholds=hint_thresholds,
+        partial_clone_ttl_seconds=args.partial_clone_ttl,
+        max_partial_clones=args.max_partial_clones,
+    )
+
+    dispatcher = Dispatcher(
+        session=session,
+        tool_descriptions=descriptions,
+        log=log,
+    )
+
+    # Transport selection: explicit --socket > --port > --stdio > default(stdio)
+    try:
+        if args.socket:
+            UnixTransport(dispatcher, log, socket_path=args.socket).serve()
+        elif args.port is not None:
+            if args.bind != "127.0.0.1":
+                log.warn("binding non-loopback — no auth on the wire",
+                         bind=args.bind, port=args.port)
+            HttpTransport(dispatcher, log, host=args.bind, port=args.port).serve()
+        else:
+            StdioTransport(dispatcher, log).serve()
+    finally:
+        session.close()
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())