archolith-mcp-framework 0.2.0__tar.gz

archolith_mcp_framework-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Archolith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

archolith_mcp_framework-0.2.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: archolith-mcp-framework
+Version: 0.2.0
+Summary: Shared FastMCP infrastructure for Archolith-compatible MCP servers.
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: fastmcp<4,>=3.2.4
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Dynamic: license-file

archolith_mcp_framework-0.2.0/README.md

@@ -0,0 +1,31 @@
+# Archolith MCP Framework
+
+`archolith-mcp-framework` is shared FastMCP infrastructure for MCP servers. It provides a server factory,
+tool-discovery transform, common middleware, response helpers, reusable mixins, and asynchronous job support.
+
+## Install
+
+```toml
+[project]
+dependencies = [
+    "archolith-mcp-framework @ git+https://github.com/Archolith/archolith-mcp-framework.git@v0.2.0",
+]
+```
+
+## Use
+
+```python
+from archolith_mcp_framework import create_gateway_server, run_server
+
+server = create_gateway_server("example")
+run_server(server)
+```
+
+## Compatibility
+
+The old `cth_mcp_framework` import remains available during migration and forwards to the same public API.
+New projects should import `archolith_mcp_framework`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

archolith_mcp_framework-0.2.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "archolith-mcp-framework"
+version = "0.2.0"
+description = "Shared FastMCP infrastructure for Archolith-compatible MCP servers."
+requires-python = ">=3.12"
+dependencies = [
+    "fastmcp>=3.2.4,<4",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

archolith_mcp_framework-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

archolith_mcp_framework-0.2.0/src/archolith_mcp_framework/__init__.py

@@ -0,0 +1,87 @@
+"""archolith-mcp-framework — shared FastMCP infrastructure.
+
+Provides:
+- create_gateway_server(): Factory for FastMCP servers with Search Transform + Middleware
+- WorkspaceSearchTransform: BM25SearchTransform with workspace-default settings
+- ErrorHandlingMiddleware, TimingMiddleware, StructuredLoggingMiddleware, TimeoutMiddleware
+- run_server(): Start a FastMCP server on stdio transport
+- ToolResponse: Standard response dataclass for tool returns
+- BaseGatewayServer: Abstract base class for MCP gateway servers
+- PathValidationMixin, ChunkedIOMixin, AuditLogMixin, GitMixin, CompactMixin: Pick-and-mix patterns
+"""
+
+from archolith_mcp_framework.server import create_gateway_server
+from archolith_mcp_framework.transforms import WorkspaceSearchTransform
+from archolith_mcp_framework.middleware import (
+    ErrorHandlingMiddleware,
+    TimingMiddleware,
+    StructuredLoggingMiddleware,
+    TimeoutMiddleware,
+)
+from archolith_mcp_framework.runner import run_server
+from archolith_mcp_framework.response import (
+    ToolResponse,
+    ERR_NOT_FOUND,
+    ERR_INVALID_INPUT,
+    ERR_PERMISSION,
+    ERR_TOO_LARGE,
+    ERR_TIMEOUT,
+    ERR_INTERNAL,
+)
+from archolith_mcp_framework.base import BaseGatewayServer
+from archolith_mcp_framework.duration_stats import (
+    DurationEstimate,
+    record_duration,
+    estimate_duration,
+)
+from archolith_mcp_framework.jobs import (
+    start_job,
+    job_status,
+    job_eta,
+    cancel_job,
+)
+from archolith_mcp_framework.mixins import (
+    PathValidationMixin,
+    ChunkedIOMixin,
+    AuditLogMixin,
+    GitMixin,
+    CompactMixin,
+    JobControlMixin,
+)
+
+__all__ = [
+    # Factory + runner
+    "create_gateway_server",
+    "run_server",
+    # Transforms + middleware
+    "WorkspaceSearchTransform",
+    "ErrorHandlingMiddleware",
+    "TimingMiddleware",
+    "StructuredLoggingMiddleware",
+    "TimeoutMiddleware",
+    # OOP layer
+    "ToolResponse",
+    "ERR_NOT_FOUND",
+    "ERR_INVALID_INPUT",
+    "ERR_PERMISSION",
+    "ERR_TOO_LARGE",
+    "ERR_TIMEOUT",
+    "ERR_INTERNAL",
+    "BaseGatewayServer",
+    # Duration stats / ETA
+    "DurationEstimate",
+    "record_duration",
+    "estimate_duration",
+    # Async job registry
+    "start_job",
+    "job_status",
+    "job_eta",
+    "cancel_job",
+    # Mixins
+    "PathValidationMixin",
+    "ChunkedIOMixin",
+    "AuditLogMixin",
+    "GitMixin",
+    "CompactMixin",
+    "JobControlMixin",
+]

archolith_mcp_framework-0.2.0/src/archolith_mcp_framework/base.py

@@ -0,0 +1,70 @@
+"""BaseGatewayServer — abstract base class for MCP gateway servers.
+
+Subclass this, set class attributes (name, instructions, always_visible),
+override _register_tools(), then call run() or pass self.mcp to run_server().
+
+The factory function create_gateway_server() remains the foundation; this
+base class is a convenience layer on top.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from fastmcp import FastMCP
+from fastmcp.server.middleware import Middleware
+
+from archolith_mcp_framework.runner import run_server
+from archolith_mcp_framework.server import create_gateway_server
+
+
+class BaseGatewayServer:
+    """Abstract base for MCP gateway servers.
+
+    Subclass this, call super().__init__(), register tools with
+    @self.mcp.tool() or @self.tool(), then call run() or pass
+    self.mcp to run_server().
+
+    Attributes:
+        name: Server name (e.g. "example.gateway", "yawn.vps").
+        instructions: Human-readable description shown to LLM clients.
+        always_visible: Tool names that stay visible alongside
+            search_tools + call_tool.
+    """
+
+    name: str = ""
+    instructions: str = ""
+    always_visible: list[str] = []
+    schema_abbreviated: bool = False
+
+    def __init__(
+        self,
+        *,
+        lifespan: Any = None,
+        middlewares: Sequence[Middleware] | None = None,
+        max_results: int = 10,
+    ) -> None:
+        self.mcp: FastMCP = create_gateway_server(
+            self.name,
+            instructions=self.instructions,
+            always_visible=self.always_visible or None,
+            lifespan=lifespan,
+            middlewares=middlewares,
+            max_results=max_results,
+            schema_abbreviated=self.schema_abbreviated,
+        )
+        self._register_tools()
+
+    def _register_tools(self) -> None:
+        """Override to register @self.mcp.tool() functions.
+
+        This is called automatically during __init__().
+        """
+
+    def tool(self, fn=None, **kwargs: Any) -> Any:
+        """Decorator shorthand: @self.tool() instead of @self.mcp.tool()."""
+        return self.mcp.tool(fn, **kwargs)
+
+    def run(self) -> None:
+        """Start the server on stdio transport."""
+        run_server(self.mcp)

archolith_mcp_framework-0.2.0/src/archolith_mcp_framework/duration_stats.py

@@ -0,0 +1,252 @@
+"""Duration statistics for async MCP jobs.
+
+Long-running tools (deploy, gradle build) run as async start + poll. A poll is a
+full model turn, so a multi-minute job that is polled every few seconds burns
+dozens of turns. The fix is to make the job *self-describing*: record how long
+each kind of job actually takes, then tell the client how long to wait before its
+first (ideally only) status check.
+
+This module records terminal-state durations per ``tool + bucket`` and returns a
+:class:`DurationEstimate` with ``p50`` (suggested first-check delay) and ``p90``
+(the "now it's worth worrying" threshold). Buckets are deliberately
+low-cardinality discriminators of runtime (gradle task name, deploy target) so
+the percentiles mean something.
+
+Storage is a small JSON file under ``<WORKSPACE_ROOT>/logs``; missing or corrupt
+files start empty (cold-start defaults cover the gap). All access is guarded by a
+module-level lock — each MCP server is a single stdio process.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+
+# Rolling window: keep at most this many recent durations per bucket.
+WINDOW = 20
+
+# Below this many samples, ignore recorded stats and use the cold-start default.
+MIN_SAMPLES = 3
+
+# Floor for the suggested first-check delay (seconds). Never advise an absurdly
+# short wait even if a bucket's p50 is tiny — a status check still costs a turn.
+MIN_FIRST_CHECK_S = 30
+
+_lock = threading.RLock()
+
+# In-memory cache of {"<tool>:<bucket>": [durations...]}. Loaded lazily.
+_cache: dict[str, list[float]] | None = None
+
+
+# ---------------------------------------------------------------------------
+# Storage path resolution
+# ---------------------------------------------------------------------------
+
+def _default_stats_path() -> Path:
+    """Resolve the stats file path from WORKSPACE_ROOT (or a sane fallback)."""
+    root = os.getenv("WORKSPACE_ROOT")
+    if root:
+        base = Path(root)
+    else:
+        # Default to the process working directory when a workspace root is not configured.
+        base = Path.cwd()
+    return base / "logs" / "mcp-duration-stats.json"
+
+
+# Resolved once at import; tests override via the ``path`` argument on helpers.
+STATS_PATH = _default_stats_path()
+
+
+# ---------------------------------------------------------------------------
+# Estimate dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class DurationEstimate:
+    """Estimated runtime for a job bucket.
+
+    Attributes:
+        p50: Median runtime in seconds. Use as the suggested first-check delay.
+        p90: 90th-percentile runtime in seconds. Past this, a running job is
+            worth worrying about even though it may still be a slow run.
+        samples: Number of recorded durations backing the estimate.
+        source: ``"stats"`` when derived from recorded samples, ``"default"``
+            when ``samples < MIN_SAMPLES`` and the cold-start default was used.
+    """
+
+    p50: float
+    p90: float
+    samples: int
+    source: str
+
+    @property
+    def suggested_first_check_s(self) -> int:
+        """Integer seconds to wait before the first status check (floored)."""
+        return max(MIN_FIRST_CHECK_S, int(round(self.p50)))
+
+    def guidance(self) -> str:
+        """One-line, LLM-facing instruction on how to wait."""
+        first = self.suggested_first_check_s
+        worry = int(round(self.p90))
+        if self.source == "default":
+            return (
+                f"No history yet; expect ~{first}s. Schedule one wakeup in ~{first}s, "
+                f"then check status once. Treat as stuck only well past ~{worry}s."
+            )
+        return (
+            f"Typically ~{first}s (p50 over {self.samples} runs). Schedule one wakeup "
+            f"in ~{first}s, then check status once. Past ~{worry}s (p90) it's worth a "
+            f"closer look; do not poll in between."
+        )
+
+
+# ---------------------------------------------------------------------------
+# Percentile math (pure)
+# ---------------------------------------------------------------------------
+
+def _percentile(sorted_values: list[float], pct: float) -> float:
+    """Linear-interpolation percentile over an already-sorted list.
+
+    ``pct`` is in [0, 100]. Returns 0.0 for an empty list.
+    """
+    if not sorted_values:
+        return 0.0
+    if len(sorted_values) == 1:
+        return float(sorted_values[0])
+    rank = (pct / 100.0) * (len(sorted_values) - 1)
+    low = int(rank)
+    high = min(low + 1, len(sorted_values) - 1)
+    frac = rank - low
+    return float(sorted_values[low] + (sorted_values[high] - sorted_values[low]) * frac)
+
+
+def _estimate_from_window(window: list[float], *, default: float) -> DurationEstimate:
+    """Build an estimate from a duration window, falling back to ``default``."""
+    samples = len(window)
+    if samples < MIN_SAMPLES:
+        return DurationEstimate(p50=float(default), p90=float(default), samples=samples, source="default")
+    ordered = sorted(window)
+    return DurationEstimate(
+        p50=_percentile(ordered, 50),
+        p90=_percentile(ordered, 90),
+        samples=samples,
+        source="stats",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Disk I/O (isolated, path-injectable for tests)
+# ---------------------------------------------------------------------------
+
+def _load(path: Path) -> dict[str, list[float]]:
+    """Load the stats document. Missing or corrupt file -> empty dict."""
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except (FileNotFoundError, OSError):
+        return {}
+    try:
+        data = json.loads(raw)
+    except (ValueError, TypeError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    result: dict[str, list[float]] = {}
+    for key, vals in data.items():
+        if isinstance(key, str) and isinstance(vals, list):
+            cleaned = [float(v) for v in vals if isinstance(v, (int, float))]
+            if cleaned:
+                result[key] = cleaned[-WINDOW:]
+    return result
+
+
+def _save(path: Path, data: dict[str, list[float]]) -> None:
+    """Atomically write the stats document."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=".dur-", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(data, f)
+        os.replace(tmp, path)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _key(tool: str, bucket: str) -> str:
+    return f"{tool}:{bucket}"
+
+
+def _get_cache(path: Path) -> dict[str, list[float]]:
+    global _cache
+    if _cache is None:
+        _cache = _load(path)
+    return _cache
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def record_duration(tool: str, bucket: str, seconds: float, *, path: Path | None = None) -> None:
+    """Record a completed job's duration into the rolling window for its bucket.
+
+    Only successful runs should be recorded — failures and timeouts skew the
+    median toward unrepresentative values. Callers enforce that policy.
+
+    Args:
+        tool: Logical tool name (e.g. ``"vps_deploy"``, ``"gradle_build"``).
+        bucket: Low-cardinality runtime discriminator (deploy target, task name).
+        seconds: Wall-clock duration of the run.
+        path: Override the stats file (tests). Defaults to :data:`STATS_PATH`.
+    """
+    if seconds < 0:
+        return
+    target = path or STATS_PATH
+    with _lock:
+        data = dict(_get_cache(target))
+        key = _key(tool, bucket)
+        window = list(data.get(key, []))
+        window.append(float(seconds))
+        data[key] = window[-WINDOW:]
+        _save(target, data)
+        global _cache
+        _cache = data
+
+
+def estimate_duration(
+    tool: str,
+    bucket: str,
+    *,
+    default: float,
+    path: Path | None = None,
+) -> DurationEstimate:
+    """Estimate runtime for a job bucket.
+
+    Returns a stats-backed estimate when at least :data:`MIN_SAMPLES` durations
+    are recorded, otherwise a default-backed estimate (``source="default"``).
+
+    Args:
+        tool: Logical tool name.
+        bucket: Low-cardinality runtime discriminator.
+        default: Cold-start expected duration in seconds for this tool.
+        path: Override the stats file (tests). Defaults to :data:`STATS_PATH`.
+    """
+    target = path or STATS_PATH
+    with _lock:
+        data = _get_cache(target)
+        window = list(data.get(_key(tool, bucket), []))
+    return _estimate_from_window(window, default=default)
+
+
+def reset_cache() -> None:
+    """Drop the in-memory cache (tests). Next access reloads from disk."""
+    global _cache
+    with _lock:
+        _cache = None