wrg-mcp-server 1.0.0__tar.gz

wrg_mcp_server-1.0.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: wrg_mcp_server
+Version: 1.0.0
+Summary: WRG MCP server — exposes WinstonRedGuard tools to Claude and AI agents
+Author-email: Yakuphan Yucel <yakuphan.yucel11@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/yakuphanycl/WinstonRedGuard/tree/main/apps/wrg_mcp_server
+Project-URL: Repository, https://github.com/yakuphanycl/WinstonRedGuard
+Project-URL: Issues, https://github.com/yakuphanycl/WinstonRedGuard/issues
+Project-URL: Documentation, https://github.com/yakuphanycl/WinstonRedGuard/tree/main/apps/wrg_mcp_server#readme
+Keywords: ai-agents,claude,mcp,model-context-protocol,winstonredguard
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: mcp<2.0,>=1.0.0
+Provides-Extra: remote
+Requires-Dist: httpx<1.0,>=0.27; extra == "remote"
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+
+<!-- mcp-name: io.github.yakuphanycl/wrg-mcp-server -->
+
+# wrg_mcp_server
+
+MCP (Model Context Protocol) server exposing the WinstonRedGuard monorepo to Claude and other MCP-compatible AI agents. Built on `FastMCP` — registers tools from every active WRG app so an agent can inspect the repo, run pipelines, query memory, and call remote services without shelling out.
+
+## Transports
+
+```bash
+wrg-mcp-server --transport stdio              # Claude Desktop / Claude Code
+wrg-mcp-server --transport streamable-http    # default HTTP (recommended)
+wrg-mcp-server --transport sse                # legacy HTTP
+```
+
+Flags: `--host 0.0.0.0` · `--port 8080` · `--mcp-path /mcp`
+
+## Install
+
+```bash
+cd apps/wrg_mcp_server
+pip install -e .             # core: MCP + local tools only
+pip install -e ".[remote]"   # adds httpx for site_* / pulseboard_* tools
+pip install -e ".[dev]"      # pytest + pytest-asyncio
+```
+
+## Tools exposed
+
+### Local (subprocess-backed, always available)
+
+| Tool | What it does |
+|---|---|
+| `connector_status` | Report which remote services are configured |
+| `app_list`, `app_info` | Query `app_registry/data/registry.json` |
+| `governance_run` | Execute `governance_check` across one or all apps |
+| `release_check` | Run the `tools/release_check.ps1` gate |
+| `pipeline_list`, `pipeline_show`, `pipeline_run` | `wrg_pipeline` DAG operations |
+| `pulse_check` | Invoke `wrg-pulse check` |
+| `memory_get`, `memory_set`, `memory_list`, `memory_search` | `wrg_memory` key-value access |
+| `research_history`, `research_report`, `research_scan`, `research_watch`, `research_scan_summary` | `research_motor` runs and artifacts |
+| `vault_audit` | `wrg_vault` audit ledger inspection |
+| `scheduler_task_list`, `scheduler_tick_dry_run` | `wrg_scheduler` inspection |
+
+### Remote (HTTP, opt-in via env)
+
+| Tool | Upstream |
+|---|---|
+| `site_health`, `site_get`, `site_post` | Company site API (`WRG_SITE_BASE_URL`) |
+| `pulseboard_health`, `pulseboard_list_repos`, `pulseboard_add_repo`, `pulseboard_delete_repo`, `pulseboard_get_pulse` | `pulseboard` dashboard (`WRG_PULSEBOARD_BASE_URL`) |
+
+Remote tools return `{"ok": false, "error": "httpx not installed — remote tools unavailable"}` when the `[remote]` extra is not installed.
+
+## Environment
+
+### Repo discovery
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `WRG_REPO_ROOT` | auto-detect (walk up until `apps/` + `CLAUDE.md`) | Required when installed from wheel outside the monorepo |
+
+### Mutation gate (default: off)
+
+State-changing tools (`memory_set`, `pipeline_run`) refuse to execute unless:
+
+```bash
+WRG_MCP_ALLOW_MUTATIONS=1
+```
+
+This prevents an MCP client from silently writing memory or launching pipelines on a read-only connection.
+
+### Remote service config
+
+Per service (`SITE` / `PULSEBOARD`), prefix with `WRG_<SERVICE>_`:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `*_BASE_URL` | — | Enables the service (unset = service disabled) |
+| `*_TOKEN` | — | Bearer token for `Authorization` header |
+| `*_AUTH_HEADER` | `Authorization` | Override header name |
+| `*_AUTH_SCHEME` | `Bearer` | Override token scheme |
+| `*_SESSION_COOKIE` | — | Optional `Cookie` header |
+| `*_EXTRA_HEADERS` | — | JSON object of extra headers |
+| `*_TIMEOUT_SECONDS` | `WRG_HTTP_TIMEOUT_SECONDS` (20.0) | Per-request timeout |
+| `*_VERIFY_TLS` | `WRG_HTTP_VERIFY_TLS` (true) | TLS verification |
+
+## Claude Code / Claude Desktop integration
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "wrg": {
+      "command": "wrg-mcp-server",
+      "args": ["--transport", "stdio"],
+      "env": {
+        "WRG_REPO_ROOT": "D:\\dev\\WinstonRedGuard",
+        "WRG_MCP_ALLOW_MUTATIONS": "0"
+      }
+    }
+  }
+}
+```
+
+## Architecture
+
+```
+FastMCP server
+├── server.py            — tool registration, remote HTTP dispatch
+├── config.py            — ServiceConfig / AppConfig from env (frozen dataclasses)
+├── http_utils.py        — URL builder, response parser
+├── local_tools.py       — subprocess wrappers for WRG CLIs (~20 tools)
+└── cli.py               — argparse entry point
+```
+
+Local tools use `subprocess.run` with `stdin=DEVNULL` (not asyncio subprocess) — avoids a Windows pipe-blocking deadlock under anyio. Tool dispatch is wrapped in `anyio.to_thread.run_sync` so the MCP event loop stays responsive.
+
+## Tests
+
+```bash
+pytest -q
+```
+
+## Status
+
+Production — 1045 lines, covers every active WRG app, drives the `mcp__wrg__*` tools visible in connected Claude sessions.

wrg_mcp_server-1.0.0/README.md

@@ -0,0 +1,125 @@
+<!-- mcp-name: io.github.yakuphanycl/wrg-mcp-server -->
+
+# wrg_mcp_server
+
+MCP (Model Context Protocol) server exposing the WinstonRedGuard monorepo to Claude and other MCP-compatible AI agents. Built on `FastMCP` — registers tools from every active WRG app so an agent can inspect the repo, run pipelines, query memory, and call remote services without shelling out.
+
+## Transports
+
+```bash
+wrg-mcp-server --transport stdio              # Claude Desktop / Claude Code
+wrg-mcp-server --transport streamable-http    # default HTTP (recommended)
+wrg-mcp-server --transport sse                # legacy HTTP
+```
+
+Flags: `--host 0.0.0.0` · `--port 8080` · `--mcp-path /mcp`
+
+## Install
+
+```bash
+cd apps/wrg_mcp_server
+pip install -e .             # core: MCP + local tools only
+pip install -e ".[remote]"   # adds httpx for site_* / pulseboard_* tools
+pip install -e ".[dev]"      # pytest + pytest-asyncio
+```
+
+## Tools exposed
+
+### Local (subprocess-backed, always available)
+
+| Tool | What it does |
+|---|---|
+| `connector_status` | Report which remote services are configured |
+| `app_list`, `app_info` | Query `app_registry/data/registry.json` |
+| `governance_run` | Execute `governance_check` across one or all apps |
+| `release_check` | Run the `tools/release_check.ps1` gate |
+| `pipeline_list`, `pipeline_show`, `pipeline_run` | `wrg_pipeline` DAG operations |
+| `pulse_check` | Invoke `wrg-pulse check` |
+| `memory_get`, `memory_set`, `memory_list`, `memory_search` | `wrg_memory` key-value access |
+| `research_history`, `research_report`, `research_scan`, `research_watch`, `research_scan_summary` | `research_motor` runs and artifacts |
+| `vault_audit` | `wrg_vault` audit ledger inspection |
+| `scheduler_task_list`, `scheduler_tick_dry_run` | `wrg_scheduler` inspection |
+
+### Remote (HTTP, opt-in via env)
+
+| Tool | Upstream |
+|---|---|
+| `site_health`, `site_get`, `site_post` | Company site API (`WRG_SITE_BASE_URL`) |
+| `pulseboard_health`, `pulseboard_list_repos`, `pulseboard_add_repo`, `pulseboard_delete_repo`, `pulseboard_get_pulse` | `pulseboard` dashboard (`WRG_PULSEBOARD_BASE_URL`) |
+
+Remote tools return `{"ok": false, "error": "httpx not installed — remote tools unavailable"}` when the `[remote]` extra is not installed.
+
+## Environment
+
+### Repo discovery
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `WRG_REPO_ROOT` | auto-detect (walk up until `apps/` + `CLAUDE.md`) | Required when installed from wheel outside the monorepo |
+
+### Mutation gate (default: off)
+
+State-changing tools (`memory_set`, `pipeline_run`) refuse to execute unless:
+
+```bash
+WRG_MCP_ALLOW_MUTATIONS=1
+```
+
+This prevents an MCP client from silently writing memory or launching pipelines on a read-only connection.
+
+### Remote service config
+
+Per service (`SITE` / `PULSEBOARD`), prefix with `WRG_<SERVICE>_`:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `*_BASE_URL` | — | Enables the service (unset = service disabled) |
+| `*_TOKEN` | — | Bearer token for `Authorization` header |
+| `*_AUTH_HEADER` | `Authorization` | Override header name |
+| `*_AUTH_SCHEME` | `Bearer` | Override token scheme |
+| `*_SESSION_COOKIE` | — | Optional `Cookie` header |
+| `*_EXTRA_HEADERS` | — | JSON object of extra headers |
+| `*_TIMEOUT_SECONDS` | `WRG_HTTP_TIMEOUT_SECONDS` (20.0) | Per-request timeout |
+| `*_VERIFY_TLS` | `WRG_HTTP_VERIFY_TLS` (true) | TLS verification |
+
+## Claude Code / Claude Desktop integration
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "wrg": {
+      "command": "wrg-mcp-server",
+      "args": ["--transport", "stdio"],
+      "env": {
+        "WRG_REPO_ROOT": "D:\\dev\\WinstonRedGuard",
+        "WRG_MCP_ALLOW_MUTATIONS": "0"
+      }
+    }
+  }
+}
+```
+
+## Architecture
+
+```
+FastMCP server
+├── server.py            — tool registration, remote HTTP dispatch
+├── config.py            — ServiceConfig / AppConfig from env (frozen dataclasses)
+├── http_utils.py        — URL builder, response parser
+├── local_tools.py       — subprocess wrappers for WRG CLIs (~20 tools)
+└── cli.py               — argparse entry point
+```
+
+Local tools use `subprocess.run` with `stdin=DEVNULL` (not asyncio subprocess) — avoids a Windows pipe-blocking deadlock under anyio. Tool dispatch is wrapped in `anyio.to_thread.run_sync` so the MCP event loop stays responsive.
+
+## Tests
+
+```bash
+pytest -q
+```
+
+## Status
+
+Production — 1045 lines, covers every active WRG app, drives the `mcp__wrg__*` tools visible in connected Claude sessions.

wrg_mcp_server-1.0.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wrg_mcp_server"
+version = "1.0.0"
+description = "WRG MCP server — exposes WinstonRedGuard tools to Claude and AI agents"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Yakuphan Yucel", email = "yakuphan.yucel11@gmail.com" }]
+keywords = [
+    "ai-agents",
+    "claude",
+    "mcp",
+    "model-context-protocol",
+    "winstonredguard",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "mcp>=1.0.0,<2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/yakuphanycl/WinstonRedGuard/tree/main/apps/wrg_mcp_server"
+Repository = "https://github.com/yakuphanycl/WinstonRedGuard"
+Issues = "https://github.com/yakuphanycl/WinstonRedGuard/issues"
+Documentation = "https://github.com/yakuphanycl/WinstonRedGuard/tree/main/apps/wrg_mcp_server#readme"
+
+[project.optional-dependencies]
+remote = [
+    "httpx>=0.27,<1.0",
+]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=0.24",
+]
+
+[project.scripts]
+wrg-mcp-server = "wrg_mcp_server.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.coverage.report]
+# Baseline no-regression floor. Apps above this today (measured 2026-04-21)
+# shouldn't drop below it; raise individually once they stabilise higher.
+fail_under = 60

wrg_mcp_server-1.0.0/setup.cfg

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

wrg_mcp_server-1.0.0/src/wrg_mcp_server/__init__.py

@@ -0,0 +1,4 @@
+"""wrg_mcp_server package."""
+
+__all__ = ["__version__"]
+__version__ = "1.0.0"

wrg_mcp_server-1.0.0/src/wrg_mcp_server/cli.py

@@ -0,0 +1,50 @@
+"""CLI entrypoint for wrg_mcp_server.
+
+Supports three transports:
+  stdio             — for Claude Desktop / Claude Code integration
+  streamable-http   — recommended HTTP transport (default)
+  sse               — legacy HTTP transport
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="wrg-mcp-server",
+        description="WinstonRedGuard MCP server",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "streamable-http", "sse"],
+        default="streamable-http",
+        help="MCP transport (default: streamable-http)",
+    )
+    parser.add_argument("--host", default="0.0.0.0", help="Bind host (default: 0.0.0.0)")
+    parser.add_argument("--port", type=int, default=8080, help="Bind port (default: 8080)")
+    parser.add_argument("--mcp-path", default="/mcp", help="HTTP endpoint path (default: /mcp)")
+
+    args = parser.parse_args()
+
+    from wrg_mcp_server.server import create_mcp_server
+
+    server = create_mcp_server(
+        host=args.host,
+        port=args.port,
+        streamable_http_path=args.mcp_path,
+    )
+
+    print(
+        f"wrg-mcp-server starting (transport={args.transport}, "
+        f"host={args.host}, port={args.port})",
+        file=sys.stderr,
+    )
+    server.run(transport=args.transport)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

wrg_mcp_server-1.0.0/src/wrg_mcp_server/config.py

@@ -0,0 +1,153 @@
+"""Environment-driven configuration for wrg_mcp_server."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from typing import Mapping
+
+
+class ConfigError(RuntimeError):
+    """Raised when connector configuration is invalid."""
+
+
+def _parse_bool(value: str | None, *, default: bool) -> bool:
+    if value is None:
+        return default
+    normalized = value.strip().lower()
+    if normalized in {"1", "true", "yes", "on"}:
+        return True
+    if normalized in {"0", "false", "no", "off"}:
+        return False
+    raise ConfigError(f"Invalid boolean value: {value!r}")
+
+
+def _parse_float(value: str | None, *, default: float, key: str) -> float:
+    if value is None or not value.strip():
+        return default
+    try:
+        parsed = float(value)
+    except ValueError as exc:
+        raise ConfigError(f"{key} must be a number: {value!r}") from exc
+    if parsed <= 0:
+        raise ConfigError(f"{key} must be > 0: {value!r}")
+    return parsed
+
+
+def _parse_headers_json(raw: str | None, *, key: str) -> dict[str, str]:
+    if raw is None or not raw.strip():
+        return {}
+    try:
+        obj = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"{key} must be valid JSON object") from exc
+
+    if not isinstance(obj, dict):
+        raise ConfigError(f"{key} must be a JSON object")
+
+    out: dict[str, str] = {}
+    for k, v in obj.items():
+        if not isinstance(k, str):
+            raise ConfigError(f"{key} keys must be strings")
+        if not isinstance(v, str):
+            raise ConfigError(f"{key} values must be strings")
+        out[k] = v
+    return out
+
+
+@dataclass(frozen=True)
+class ServiceConfig:
+    """Configuration for one upstream service."""
+
+    base_url: str
+    token: str | None
+    auth_header: str
+    auth_scheme: str
+    session_cookie: str | None
+    extra_headers: dict[str, str]
+    timeout_seconds: float
+    verify_tls: bool
+
+    def build_headers(self) -> dict[str, str]:
+        headers: dict[str, str] = dict(self.extra_headers)
+        if self.token:
+            token_value = f"{self.auth_scheme} {self.token}".strip()
+            headers[self.auth_header] = token_value
+        if self.session_cookie:
+            headers["Cookie"] = self.session_cookie
+        return headers
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    """Top-level connector configuration."""
+
+    site: ServiceConfig | None
+    pulseboard: ServiceConfig | None
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str]) -> "AppConfig":
+        default_timeout = _parse_float(
+            env.get("WRG_HTTP_TIMEOUT_SECONDS"),
+            default=20.0,
+            key="WRG_HTTP_TIMEOUT_SECONDS",
+        )
+        default_verify_tls = _parse_bool(
+            env.get("WRG_HTTP_VERIFY_TLS"),
+            default=True,
+        )
+
+        site = _service_from_env(
+            env=env,
+            prefix="WRG_SITE",
+            base_url=env.get("WRG_SITE_BASE_URL"),
+            default_timeout=default_timeout,
+            default_verify_tls=default_verify_tls,
+        )
+        pulseboard = _service_from_env(
+            env=env,
+            prefix="WRG_PULSEBOARD",
+            base_url=env.get("WRG_PULSEBOARD_BASE_URL"),
+            default_timeout=default_timeout,
+            default_verify_tls=default_verify_tls,
+        )
+        return cls(site=site, pulseboard=pulseboard)
+
+
+def _service_from_env(
+    *,
+    env: Mapping[str, str],
+    prefix: str,
+    base_url: str | None,
+    default_timeout: float,
+    default_verify_tls: bool,
+) -> ServiceConfig | None:
+    if base_url is None or not base_url.strip():
+        return None
+
+    timeout_seconds = _parse_float(
+        env.get(f"{prefix}_TIMEOUT_SECONDS"),
+        default=default_timeout,
+        key=f"{prefix}_TIMEOUT_SECONDS",
+    )
+    verify_tls = _parse_bool(
+        env.get(f"{prefix}_VERIFY_TLS"),
+        default=default_verify_tls,
+    )
+    extra_headers = _parse_headers_json(
+        env.get(f"{prefix}_EXTRA_HEADERS"),
+        key=f"{prefix}_EXTRA_HEADERS",
+    )
+    auth_scheme = env.get(f"{prefix}_AUTH_SCHEME", "Bearer").strip()
+    auth_header = env.get(f"{prefix}_AUTH_HEADER", "Authorization").strip()
+
+    return ServiceConfig(
+        base_url=base_url.rstrip("/"),
+        token=(env.get(f"{prefix}_TOKEN") or "").strip() or None,
+        auth_header=auth_header or "Authorization",
+        auth_scheme=auth_scheme,
+        session_cookie=(env.get(f"{prefix}_SESSION_COOKIE") or "").strip() or None,
+        extra_headers=extra_headers,
+        timeout_seconds=timeout_seconds,
+        verify_tls=verify_tls,
+    )

wrg_mcp_server-1.0.0/src/wrg_mcp_server/http_utils.py

@@ -0,0 +1,70 @@
+"""HTTP utility helpers.
+
+These are only used when httpx is installed (for remote site/pulseboard tools).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+from urllib.parse import parse_qsl, urlencode, urljoin, urlparse
+
+
+def normalize_relative_path(path: str) -> str:
+    """Normalize user path and reject absolute/unsafe input."""
+    clean = path.strip()
+    if not clean:
+        return "/"
+    if "://" in clean:
+        raise ValueError("Absolute URLs are not allowed; provide a relative path.")
+    if clean.startswith("//"):
+        raise ValueError("Path must not start with //.")
+    if not clean.startswith("/"):
+        clean = f"/{clean}"
+    return clean
+
+
+def build_url(base_url: str, path: str, query: Mapping[str, Any] | None = None) -> str:
+    """Build a final URL from base and safe relative path."""
+    normalized = normalize_relative_path(path)
+    parsed = urlparse(normalized)
+    if parsed.scheme or parsed.netloc:
+        raise ValueError("Path must be relative.")
+
+    absolute = urljoin(f"{base_url.rstrip('/')}/", parsed.path.lstrip("/"))
+
+    merged: dict[str, str] = dict(parse_qsl(parsed.query, keep_blank_values=True))
+    if query:
+        for key, value in query.items():
+            if value is None:
+                continue
+            merged[str(key)] = str(value)
+    if not merged:
+        return absolute
+    return f"{absolute}?{urlencode(merged)}"
+
+
+def parse_response(response: Any) -> dict[str, Any]:
+    """Parse httpx response body in a tool-friendly format."""
+    content_type = response.headers.get("content-type", "")
+    body: Any
+    if "application/json" in content_type.lower():
+        try:
+            body = response.json()
+        except ValueError:
+            body = _truncate_text(response.text)
+    else:
+        body = _truncate_text(response.text)
+
+    return {
+        "ok": response.is_success,
+        "status_code": response.status_code,
+        "url": str(response.url),
+        "content_type": content_type,
+        "body": body,
+    }
+
+
+def _truncate_text(value: str, max_chars: int = 4000) -> str:
+    if len(value) <= max_chars:
+        return value
+    return f"{value[:max_chars]}...(truncated)"