pi-codemcp 0.1.0

package/sidecar/json_types.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from pydantic import TypeAdapter
+
+type JsonScalar = bool | int | float | str | None
+type JsonValue = JsonScalar | list[JsonValue] | dict[str, JsonValue]
+type JsonObject = dict[str, JsonValue]
+type JsonSchema = JsonObject | bool
+
+JSON_VALUE_ADAPTER: TypeAdapter[JsonValue] = TypeAdapter(JsonValue)
+JSON_OBJECT_ADAPTER: TypeAdapter[JsonObject] = TypeAdapter(JsonObject)

package/sidecar/mcp_config.py

@@ -0,0 +1,278 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from typing import TYPE_CHECKING
+
+from fastmcp.client.auth import OAuth
+from fastmcp.mcp_config import (
+    MCPConfig,
+    RemoteMCPServer,
+    StdioMCPServer,
+    infer_transport_type_from_url,
+)
+from key_value.aio.stores.filetree import FileTreeStore
+from key_value.aio.stores.filetree.store import (
+    FileTreeV1CollectionSanitizationStrategy,
+    FileTreeV1KeySanitizationStrategy,
+)
+from pydantic import BaseModel, ConfigDict
+
+from .json_types import JSON_VALUE_ADAPTER, JsonObject, JsonValue
+from .models import NormalizedServerInfo, ServerAuth
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    import httpx
+
+PI_ONLY_FIELDS = {"directTools", "lifecycle", "idleTimeout", "disabled", "enabled"}
+REMOTE_TRANSPORTS = {"http", "streamable-http", "sse"}
+BASE_CHILD_ENV_KEYS = {
+    "CI",
+    "COLORTERM",
+    "FORCE_COLOR",
+    "HOME",
+    "LANG",
+    "LOGNAME",
+    "NO_COLOR",
+    "PATH",
+    "PI_CODING_AGENT_DIR",
+    "SHELL",
+    "TEMP",
+    "TERM",
+    "TMP",
+    "TMPDIR",
+    "USER",
+}
+ENV_ALLOWLIST_KEYS = ("MY_PI_CHILD_ENV_ALLOWLIST", "MY_PI_MCP_ENV_ALLOWLIST")
+ENV_REFERENCE_PATTERN = re.compile(r"\$\{([^}]+)\}")
+
+
+class NormalizedConfig(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid", strict=True)
+
+    config: MCPConfig
+    servers: list[NormalizedServerInfo]
+
+
+def load_mcp_json(path: Path) -> JsonObject:
+    if not path.exists():
+        raise FileNotFoundError(f"MCP config not found: {path}")
+    raw = path.read_text(encoding="utf-8").strip()
+    if not raw:
+        raise ValueError(f"MCP config is empty: {path}")
+    parsed = JSON_VALUE_ADAPTER.validate_json(raw)
+    if not isinstance(parsed, dict):
+        raise TypeError("mcp.json root must be an object")
+    return parsed
+
+
+def _string_record(
+    value: JsonValue | None,
+    *,
+    label: str,
+    server_name: str,
+) -> JsonObject:
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise TypeError(f"MCP server {server_name!r} {label} must be an object")
+    result: JsonObject = {}
+    for key, entry in value.items():
+        if not isinstance(entry, str):
+            raise TypeError(f"MCP server {server_name!r} {label}.{key} must be a string")
+        result[key] = entry
+    return result
+
+
+def _child_process_environment(
+    explicit_value: JsonValue | None,
+    *,
+    server_name: str,
+) -> JsonObject:
+    allowed_keys = set(BASE_CHILD_ENV_KEYS)
+    allowed_keys.update(key for key in os.environ if key.startswith("LC_"))
+    for allowlist_key in ENV_ALLOWLIST_KEYS:
+        allowed_keys.update(
+            key.strip() for key in os.environ.get(allowlist_key, "").split(",") if key.strip()
+        )
+
+    environment: JsonObject = {key: os.environ[key] for key in allowed_keys if key in os.environ}
+    environment.update(_string_record(explicit_value, label="env", server_name=server_name))
+    return environment
+
+
+def _expanded_headers(value: JsonValue, *, server_name: str) -> JsonObject:
+    headers = _string_record(value, label="headers", server_name=server_name)
+    environment = _child_process_environment(None, server_name=server_name)
+
+    def replace(match: re.Match[str]) -> str:
+        replacement = environment.get(match.group(1))
+        return replacement if isinstance(replacement, str) else ""
+
+    return {
+        key: ENV_REFERENCE_PATTERN.sub(replace, header)
+        for key, header in headers.items()
+        if isinstance(header, str)
+    }
+
+
+def _required_string(value: JsonValue | None, *, label: str, server_name: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise TypeError(f"MCP server {server_name!r} {label} must be a non-empty string")
+    return value
+
+
+def _disabled_server_info(
+    name: str,
+    config: JsonObject,
+    config_fingerprint: str,
+) -> NormalizedServerInfo:
+    if "command" in config:
+        _required_string(config.get("command"), label="command", server_name=name)
+        return NormalizedServerInfo(
+            name=name,
+            transport="stdio",
+            config_fingerprint=config_fingerprint,
+            enabled=False,
+        )
+    if "url" in config:
+        url = _required_string(config.get("url"), label="url", server_name=name)
+        transport = config.get("transport") or config.get("type")
+        if transport is None:
+            transport = infer_transport_type_from_url(url)
+        if not isinstance(transport, str) or transport not in REMOTE_TRANSPORTS:
+            raise ValueError(f"Unsupported MCP transport for {name}: {transport}")
+        raw_auth = config.get("auth")
+        auth_kind: ServerAuth | None = (
+            "oauth"
+            if raw_auth == "oauth"
+            else "bearer"
+            if isinstance(raw_auth, str) and raw_auth
+            else None
+        )
+        return NormalizedServerInfo(
+            name=name,
+            transport="sse" if transport == "sse" else "http",
+            config_fingerprint=config_fingerprint,
+            enabled=False,
+            auth=auth_kind,
+        )
+    raise ValueError(f"MCP server {name!r} must define either command or url")
+
+
+def normalize_mcp_config(
+    raw_config: JsonObject,
+    *,
+    oauth_storage_dir: Path,
+    oauth_client_name: str = "pi-codemcp",
+) -> NormalizedConfig:
+    server_block = raw_config.get("mcpServers", raw_config)
+    if not isinstance(server_block, dict):
+        raise TypeError("mcp.json must contain an object at the root or under mcpServers")
+
+    oauth_storage_dir.mkdir(parents=True, exist_ok=True)
+    oauth_storage = FileTreeStore(
+        data_directory=oauth_storage_dir,
+        key_sanitization_strategy=FileTreeV1KeySanitizationStrategy(oauth_storage_dir),
+        collection_sanitization_strategy=FileTreeV1CollectionSanitizationStrategy(
+            oauth_storage_dir
+        ),
+    )
+    normalized_servers: dict[str, StdioMCPServer | RemoteMCPServer] = {}
+    server_infos: list[NormalizedServerInfo] = []
+
+    for name, value in server_block.items():
+        if not isinstance(value, dict):
+            raise TypeError(f"MCP server {name!r} must be an object")
+        cleaned: JsonObject = {
+            key: item for key, item in value.items() if key not in PI_ONLY_FIELDS
+        }
+        config_fingerprint = _server_config_fingerprint(name, cleaned)
+        if value.get("disabled") is True or value.get("enabled") is False:
+            server_infos.append(_disabled_server_info(name, cleaned, config_fingerprint))
+            continue
+
+        if "command" in cleaned:
+            cleaned["env"] = _child_process_environment(
+                cleaned.get("env"),
+                server_name=name,
+            )
+            stdio_server = StdioMCPServer.model_validate({
+                **cleaned,
+                "transport": "stdio",
+                "type": "stdio",
+            })
+            normalized_servers[name] = stdio_server
+            server_infos.append(
+                NormalizedServerInfo(
+                    name=name,
+                    transport="stdio",
+                    config_fingerprint=config_fingerprint,
+                    description=stdio_server.description,
+                )
+            )
+            continue
+
+        if "url" in cleaned:
+            url = _required_string(cleaned.get("url"), label="url", server_name=name)
+            transport = cleaned.get("transport") or cleaned.get("type")
+            if transport is None:
+                transport = infer_transport_type_from_url(url)
+            if not isinstance(transport, str) or transport not in REMOTE_TRANSPORTS:
+                raise ValueError(f"Unsupported MCP transport for {name}: {transport}")
+            raw_headers = cleaned.get("headers")
+            if raw_headers is not None:
+                cleaned["headers"] = _expanded_headers(raw_headers, server_name=name)
+            raw_auth = cleaned.get("auth")
+            auth: str | httpx.Auth | None
+            auth_kind: ServerAuth | None = None
+            if raw_auth == "oauth":
+                auth = OAuth(
+                    mcp_url=url,
+                    client_name=oauth_client_name,
+                    token_storage=oauth_storage,
+                )
+                auth_kind = "oauth"
+            elif isinstance(raw_auth, str):
+                auth = raw_auth or None
+                auth_kind = "bearer" if raw_auth else None
+            elif raw_auth is None:
+                auth = None
+            else:
+                raise TypeError(f"MCP server {name!r} auth must be a string")
+            remote_server = RemoteMCPServer.model_validate({
+                **cleaned,
+                "transport": transport,
+                "auth": auth,
+            })
+            normalized_servers[name] = remote_server
+            server_infos.append(
+                NormalizedServerInfo(
+                    name=name,
+                    transport="sse" if transport == "sse" else "http",
+                    config_fingerprint=config_fingerprint,
+                    auth=auth_kind,
+                    description=remote_server.description,
+                )
+            )
+            continue
+
+        raise ValueError(f"MCP server {name!r} must define either command or url")
+
+    return NormalizedConfig(
+        config=MCPConfig(mcpServers=normalized_servers),
+        servers=server_infos,
+    )
+
+
+def _server_config_fingerprint(name: str, config: JsonObject) -> str:
+    payload = json.dumps(
+        {"name": name, "config": config},
+        sort_keys=True,
+        separators=(",", ":"),
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()

package/sidecar/models.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_serializer
+
+type ServerTransport = Literal["stdio", "http", "sse"]
+type ServerAuth = Literal["oauth", "bearer"]
+
+
+class NormalizedServerInfo(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    name: str
+    transport: ServerTransport
+    config_fingerprint: str
+    enabled: bool = True
+    auth: ServerAuth | None = None
+    description: str | None = None
+
+
+class ToolSchemaView(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    name: str
+    call: str
+    source: Literal["mcp_tool", "saved_chain"]
+    server: str | None = None
+    description: str | None = None
+    signature: str
+    stub: str
+
+    @model_serializer(mode="plain")
+    def serialize_compact(self) -> dict[str, object]:
+        values: dict[str, object] = {
+            "name": self.name,
+            "call": self.call,
+            "source": self.source,
+            "signature": self.signature,
+            "stub": self.stub,
+        }
+        if self.server is not None:
+            values["server"] = self.server
+        if self.description is not None:
+            values["description"] = self.description
+        return values
+
+
+class ServerToolSummary(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    name: str
+    tool_count: int
+
+
+class SearchResponse(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    total_tool_count: int
+    servers: list[ServerToolSummary]
+    results: list[ToolSchemaView]
+
+
+class UpstreamToolStatus(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    name: str
+    enabled: bool = True
+    description: str | None = None
+
+
+class UpstreamStatus(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    name: str
+    transport: ServerTransport
+    enabled: bool = True
+    connected: bool = False
+    discovered: bool = False
+    auth: ServerAuth | None = None
+    tool_count: int = 0
+    total_tool_count: int = 0
+    tools: list[UpstreamToolStatus] = Field(default_factory=list)
+
+
+class StatusResponse(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    connected: bool
+    config_path: str
+    tool_count: int = 0
+    upstreams: list[UpstreamStatus] = Field(default_factory=list)

package/sidecar/pyproject.toml

@@ -0,0 +1,144 @@
+[project]
+name = "pi-codemcp-sidecar"
+version = "0.1.0"
+description = "Python sidecar for pi-codemcp"
+requires-python = ">=3.12"
+dependencies = [
+  "fastmcp==3.4.4",
+  "httpx==0.28.1",
+  "pydantic==2.13.4",
+  "pydantic-monty==0.0.18",
+  "py-key-value-aio[filetree,pydantic]==0.4.5",
+  "rapidfuzz==3.14.5",
+]
+
+[dependency-groups]
+dev = [
+  "mypy==2.2.0",
+  "prek==0.4.8",
+  "pytest==8.4.2",
+  "pytest-asyncio==1.4.0",
+  "ruff==0.15.21",
+  "ty==0.0.58",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = [".."]
+
+[tool.ruff]
+required-version = "==0.15.21"
+target-version = "py312"
+line-length = 100
+src = ["sidecar"]
+preview = true
+force-exclude = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  "COM812", # Conflicts with the formatter.
+  "CPY001", # Legal copyright text is not configured.
+  "D100",   # Internal modules do not need module docstrings.
+  "D101",   # Pydantic catalog models are self-describing.
+  "D102",   # Internal methods are covered by types and focused class documentation.
+  "D103",   # Internal functions are covered by types and focused module documentation.
+  "D104",   # Internal packages do not need package docstrings beyond sidecar/__init__.py.
+  "D105",   # Magic methods do not need docstrings.
+  "D107",   # Constructor contracts are expressed by typed fields.
+  "D203",   # Incompatible with D211.
+  "D213",   # Incompatible with D212.
+  "DOC201", # Return types are explicit and checked.
+  "DOC501", # Repeating raised exception types in docstrings reduces readability.
+  "EM101",  # Inline exception messages are clearer at the failure site.
+  "EM102",  # Inline contextual exception messages are clearer at the failure site.
+  "FBT001", # JSON Schema itself may be boolean; these are not boolean control arguments.
+  "TRY003", # Custom exception wrappers would obscure concise boundary failures.
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["sidecar"]
+
+[tool.ruff.lint.mccabe]
+# JSON Schema compilation and execution-state handling are branch-heavy by nature.
+max-complexity = 20
+
+[tool.ruff.lint.pylint]
+max-args = 8
+max-bool-expr = 5
+max-branches = 20
+max-locals = 25
+max-nested-blocks = 4
+max-positional-args = 6
+max-public-methods = 10
+max-returns = 16
+max-statements = 50
+max-statements-in-try = 4
+
+[tool.ruff.format]
+docstring-code-format = true
+docstring-code-line-length = 100
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+  "ANN",
+  "D",
+  "PLR2004",
+  "S101",
+  "S105",
+  "S106",
+  "SLF001",
+]
+"tests/fixtures/**/*.py" = ["T201"]
+
+[tool.mypy]
+python_version = "3.12"
+plugins = ["pydantic.mypy"]
+strict = true
+files = [
+  "sidecar",
+  "tests/python/test_executor.py",
+  "tests/python/test_settings.py",
+]
+pretty = true
+show_error_codes = true
+show_error_code_links = true
+show_error_context = true
+show_error_end = true
+strict_bytes = true
+strict_equality_for_none = true
+warn_unreachable = true
+warn_unused_configs = true
+enable_error_code = [
+  "deprecated",
+  "exhaustive-match",
+  "explicit-override",
+  "ignore-without-code",
+  "mutable-override",
+  "possibly-undefined",
+  "redundant-expr",
+  "truthy-bool",
+  "truthy-iterable",
+  "unimported-reveal",
+]
+
+[tool.pydantic-mypy]
+init_forbid_extra = true
+init_typed = true
+warn_required_dynamic_aliases = true
+warn_untyped_fields = true
+
+[tool.ty.environment]
+python-version = "3.12"
+
+[tool.ty.rules]
+all = "error"
+
+[tool.ty.analysis]
+respect-type-ignore-comments = false
+
+[tool.ty.terminal]
+error-on-warning = true
+
+[tool.uv]
+package = false

package/sidecar/settings.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .executor import ExecutionSettings
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def _camel_case(name: str) -> str:
+    head, *tail = name.split("_")
+    alias = head + "".join(part.capitalize() for part in tail)
+    return f"{alias[:-3]}KiB" if alias.endswith("Kib") else alias
+
+
+class CodeMcpSettings(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=_camel_case,
+        populate_by_name=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    version: Literal[1] = 1
+    background_warmup: bool = True
+    cache_ttl_hours: int = Field(default=24, ge=0, le=720)
+    execution_timeout_seconds: int = Field(default=30, ge=1, le=300)
+    tool_timeout_seconds: int = Field(default=30, ge=1, le=300)
+    max_calls: int = Field(default=50, ge=1, le=200)
+    result_limit_kib: int = Field(default=16, ge=1, le=1024)
+    output_limit_kib: int = Field(default=50, ge=1, le=1024)
+    output_line_limit: int = Field(default=2000, ge=1, le=10000)
+    disabled_tools: dict[str, list[str]] = Field(default_factory=dict)
+
+    def tool_enabled(self, server: str, tool: str) -> bool:
+        return tool not in self.disabled_tools.get(server, ())
+
+    def execution_settings(self) -> ExecutionSettings:
+        return ExecutionSettings(
+            timeout_seconds=self.execution_timeout_seconds,
+            max_calls=self.max_calls,
+            tool_timeout_seconds=self.tool_timeout_seconds,
+            result_byte_limit=self.result_limit_kib * 1024,
+        )
+
+    @property
+    def cache_ttl_seconds(self) -> int:
+        return self.cache_ttl_hours * 60 * 60
+
+
+def load_settings(path: Path) -> CodeMcpSettings:
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return CodeMcpSettings()
+    return CodeMcpSettings.model_validate_json(raw)