codrspot-processor-mcp 0.1.0__py3-none-any.whl

codepreproc_client/layer1_business/mcp/server.py

@@ -0,0 +1,656 @@
+"""stdio MCP server implementation."""
+
+from __future__ import annotations
+
+import asyncio
+import importlib.metadata
+import json
+import logging
+import os
+import time
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+from urllib.parse import urlparse
+from urllib.request import url2pathname
+
+# GitPython raises ImportError at import time if no `git` executable is on
+# PATH; downgrade to a warning so a missing/unusual PATH doesn't take down
+# the whole MCP server (git-dependent tools would just fail when used).
+os.environ.setdefault("GIT_PYTHON_REFRESH", "warn")
+
+from dotenv import load_dotenv
+
+def _default_codepreproc_home() -> str:
+    try:
+        return str(Path.home() / ".codepreproc")
+    except RuntimeError:
+        return str(Path(".codepreproc").resolve())
+
+
+# Try the source-tree path first (editable install), then the canonical home location.
+load_dotenv(Path(__file__).parents[4] / ".env", override=False)
+load_dotenv(Path(os.environ.get("CODEPREPROC_HOME") or _default_codepreproc_home()) / ".env", override=False)
+
+import anyio
+import mcp.types as types
+from mcp.server.models import InitializationOptions
+from mcp.server.stdio import stdio_server
+from mcp.types import ServerCapabilities, ToolsCapability
+
+# Stdio MCP transport treats every byte on stdout as JSON-RPC. Some transitive
+# dependencies (e.g. bm25s's benchmark helper) `print()` a Windows fallback
+# notice at import time, which corrupts the stream — redirect stdout to
+# stderr for the duration of these imports so that noise lands somewhere safe.
+import sys as _sys
+from contextlib import redirect_stdout as _redirect_stdout
+
+with _redirect_stdout(_sys.stderr):
+    from codepreproc_client.layer1_business.config import (
+        apply_env_overrides,
+        get_credentials_path,
+        get_home_dir,
+        get_server_url,
+        get_settings,
+        get_superkg_settings,
+    )
+    from codepreproc_client.layer1_business.local_registry import load_local_projects
+    from codepreproc_client.layer2_tooling.condensation.session_vector_store import SessionVectorStore
+    from codepreproc_client.layer1_business.api_client.reasoning_client import LLMRuntime
+    from codepreproc_client.layer1_business.mcp.action_monitor import ActionMonitor, ToolExecutionError
+    from codepreproc_client.layer1_business.mcp.lifecycle import (
+        InstrumentedServer,
+        MCPConnectionLifecycleLogger,
+        resolve_session_roots,
+    )
+    from codepreproc_client.layer1_business.mcp.tools import CodepreprocTools, SessionState
+    from codepreproc_client.layer1_business.project_registry import ProjectRegistry
+    from codepreproc_client.layer1_business.api_client.superkg_client import SuperKGClient
+
+
+def configure_logging(log_dir: Path, debug: bool) -> logging.Logger:
+    """Configure application logging."""
+
+    log_dir.mkdir(parents=True, exist_ok=True)
+    logger = logging.getLogger("codepreproc")
+    logger.setLevel(logging.DEBUG if debug else logging.INFO)
+    logger.handlers.clear()
+    handler = RotatingFileHandler(log_dir / "mcp_server.log", maxBytes=10 * 1024 * 1024, backupCount=5, encoding="utf-8")
+    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s %(message)s"))
+    logger.addHandler(handler)
+    return logger
+
+
+def _tool_schema(properties: dict, required: list[str] | None = None) -> dict:
+    return {"type": "object", "properties": properties, "required": required or []}
+
+
+def _path_from_file_uri(uri: str) -> Path:
+    parsed = urlparse(uri)
+    if parsed.scheme != "file":
+        raise ValueError(f"Unsupported root URI scheme: {parsed.scheme!r}")
+    raw_path = f"//{parsed.netloc}{parsed.path}" if parsed.netloc else parsed.path
+    return Path(url2pathname(raw_path)).resolve()
+
+
+async def _mint_bootstrap_jwt(local_projects: dict) -> tuple[str | None, "JWTClient | None"]:
+    """Mint a JWT using any one locally registered project's fingerprint, for
+    calls that aren't project-scoped (shared defaults, the snippet library,
+    LLM reasoning). Returns (None, None) if no project is registered yet or
+    the server is unreachable - the MCP server must still start offline,
+    degrading to library defaults. The returned JWTClient is reused (rather
+    than re-minting) so later calls only re-mint once the lease nears expiry."""
+    from codepreproc_client.layer1_business.license.fingerprint import derive_fingerprint
+    from codepreproc_client.layer1_business.license.jwt_client import JWTClient
+    from codepreproc_client.layer1_business.manifest.credentials import load_manifest
+
+    if not local_projects:
+        return None, None
+    try:
+        any_project = next(iter(local_projects.values()))
+        manifest = load_manifest(get_credentials_path())
+        attestation = derive_fingerprint(any_project.project_id, any_project.root)
+        jwt_client = JWTClient(base_url=get_server_url(), manifest=manifest, fingerprint_attestation=attestation)
+        jwt = await jwt_client.get_bearer_token()
+        return jwt, jwt_client
+    except Exception:
+        return None, None
+
+
+async def _load_defaults(jwt: str | None):
+    from contracts.dtos import DefaultsConfig
+
+    if jwt is None:
+        return DefaultsConfig()
+    try:
+        from codepreproc_client.layer1_business.api_client.registry_client import get_defaults
+
+        return await get_defaults(base_url=get_server_url(), jwt=jwt)
+    except Exception:
+        return DefaultsConfig()
+
+
+async def main() -> None:
+    settings = get_settings()
+
+    from contracts.dtos import Registry as _Registry
+
+    local_projects = load_local_projects(get_home_dir())
+    bootstrap_jwt, bootstrap_jwt_client = await _mint_bootstrap_jwt(local_projects)
+    defaults = await _load_defaults(bootstrap_jwt)
+    registry_data = apply_env_overrides(_Registry(defaults=defaults, projects=local_projects))
+
+    settings.defaults = registry_data.defaults
+    logger = configure_logging(settings.logs_dir, settings.debug)
+    lifecycle_logger = MCPConnectionLifecycleLogger(
+        logging.getLogger("codepreproc.mcp.lifecycle"),
+        settings.mcp_connection_verbosity,
+    )
+    await lifecycle_logger.emit(
+        "server_start",
+        fields={
+            "pid": os.getpid(),
+            "version_source": "package_metadata",
+        },
+        verbose_fields={
+            "log_path": str(settings.logs_dir / "mcp_server.log"),
+            "connection_verbosity": settings.mcp_connection_verbosity,
+            "debug_enabled": settings.debug,
+        },
+        mirror_to_client=False,
+    )
+    # Source-chunk vectors never leave the client machine (architecture doc S2/S3):
+    # this is a local embedded store, never a network endpoint, regardless of
+    # registry_data.defaults.qdrant_url/qdrant_grpc (those configure the
+    # server-side canonical gist store instead, see gist_embedder.py).
+    qdrant_store = SessionVectorStore(path=settings.indexes_dir / "session_vectors")
+    logger.info("session_vector_store_init path=%s", settings.indexes_dir / "session_vectors")
+
+    async def _reasoning_jwt_provider() -> str:
+        if bootstrap_jwt_client is None:
+            raise RuntimeError("no project registered yet - cannot mint a JWT for LLM reasoning calls")
+        return await bootstrap_jwt_client.get_bearer_token()
+
+    llm_runtime = LLMRuntime(get_server_url(), _reasoning_jwt_provider)
+    project_registry = ProjectRegistry(registry_data)
+
+    # Any /v1/superkg/* (or other project-scoped) call must present a JWT
+    # naming that specific project_id in claims["project_ids"] (see
+    # layer2_infra/api/authz.py on the server) - the single shared
+    # bootstrap_jwt above only names whichever project was first found, so
+    # it can't be reused here. Mint (and cache) one JWT per project instead.
+    _project_jwt_clients: dict[str, "JWTClient"] = {}
+
+    async def _project_jwt_provider(project_id: str) -> str:
+        from codepreproc_client.layer1_business.license.fingerprint import derive_fingerprint
+        from codepreproc_client.layer1_business.license.jwt_client import JWTClient
+        from codepreproc_client.layer1_business.manifest.credentials import load_manifest
+
+        client = _project_jwt_clients.get(project_id)
+        if client is None:
+            project = project_registry.registry.projects.get(project_id)
+            if project is None:
+                raise RuntimeError(f"unknown project_id={project_id!r} - cannot mint a JWT for it")
+            manifest = load_manifest(get_credentials_path())
+            attestation = derive_fingerprint(project_id, project.root)
+            client = JWTClient(base_url=get_server_url(), manifest=manifest, fingerprint_attestation=attestation)
+            _project_jwt_clients[project_id] = client
+        return await client.get_bearer_token()
+
+    superkg_enabled, superkg_enrich_timeout = get_superkg_settings()
+    superkg = SuperKGClient(
+        base_url=get_server_url(),
+        jwt_provider=_project_jwt_provider,
+        enabled=superkg_enabled,
+        enrich_timeout=superkg_enrich_timeout,
+    )
+
+    from codepreproc_client.layer2_tooling.materialization.snippet.loader import SnippetLoader
+
+    snippet_loader = await SnippetLoader.from_api(
+        base_url=get_server_url(), jwt=bootstrap_jwt, base_dir=settings.home_dir
+    )
+
+    tools = CodepreprocTools(
+        settings,
+        project_registry,
+        qdrant_store,
+        llm_runtime,
+        logger,
+        superkg,
+        snippet_loader=snippet_loader,
+        jwt_provider=_project_jwt_provider,
+    )
+    sessions: dict[int, SessionState] = {}
+    # NOTE (Phase 4/5 follow-up): once lease_client.lease_world_model() is called
+    # against a real deployed server, each SessionState should own a
+    # WorldModelLeaseGuard (mcp/lifecycle.py) populated from that response, and
+    # tool handlers should read from guard.lease instead of hitting the API
+    # per-op. The guard's discard() must run when the session's last call
+    # completes - it's already wired for atexit/SIGINT/SIGTERM/SIGBREAK.
+
+    server = InstrumentedServer("codepreproc", lifecycle_logger=lifecycle_logger)
+
+    @server.list_tools()
+    async def list_tools() -> list[types.Tool]:
+        return [
+            types.Tool(name="list_projects", description="List configured projects", inputSchema=_tool_schema({})),
+            types.Tool(name="switch_project", description="Set the active project for this session", inputSchema=_tool_schema({"project": {"type": "string"}}, ["project"])),
+            types.Tool(
+                name="analyze_request",
+                description="Analyze a coding request and return a semantic execution pack",
+                inputSchema=_tool_schema({"prompt": {"type": "string"}, "project": {"type": ["string", "null"]}}, ["prompt"]),
+            ),
+            types.Tool(
+                name="analyze_filesystem_reorg",
+                description="Analyze a filesystem move or rename request and cache a validated reorganization plan",
+                inputSchema=_tool_schema({"prompt": {"type": "string"}, "project": {"type": ["string", "null"]}}, ["prompt"]),
+            ),
+            types.Tool(name="preview_semantic_plan", description="Fetch the semantic plan for a task", inputSchema=_tool_schema({"task_id": {"type": "string"}}, ["task_id"])),
+            types.Tool(name="preview_filesystem_plan", description="Fetch the cached filesystem reorganization plan for a task", inputSchema=_tool_schema({"task_id": {"type": "string"}}, ["task_id"])),
+            types.Tool(name="preview_patch", description="Fetch materialized patches for a task", inputSchema=_tool_schema({"task_id": {"type": "string"}}, ["task_id"])),
+            types.Tool(name="validate_patch", description="Fetch the structural validation outcome for a task", inputSchema=_tool_schema({"task_id": {"type": "string"}}, ["task_id"])),
+            types.Tool(
+                name="disambiguate_region",
+                description="Continue an ambiguous task from a chosen region",
+                inputSchema=_tool_schema({"task_id": {"type": "string"}, "chosen_region_id": {"type": "string"}}, ["task_id", "chosen_region_id"]),
+            ),
+            types.Tool(
+                name="apply_patch",
+                description="Apply one or all materialized patches for a task",
+                inputSchema=_tool_schema({"task_id": {"type": "string"}, "patch_index": {"type": ["integer", "null"]}}, ["task_id"]),
+            ),
+            types.Tool(
+                name="apply_filesystem_plan",
+                description="Apply a cached filesystem move or rename plan",
+                inputSchema=_tool_schema({"task_id": {"type": "string"}}, ["task_id"]),
+            ),
+            types.Tool(
+                name="usage_report",
+                description="Return accumulated LLM usage and cost",
+                inputSchema=_tool_schema({"project": {"type": ["string", "null"]}, "since_days": {"type": "integer"}}),
+            ),
+            types.Tool(
+                name="set_llm_policy",
+                description="Override a project's LLM policy for the current session",
+                inputSchema=_tool_schema({"project": {"type": "string"}, "policy": {"type": "string"}}, ["project", "policy"]),
+            ),
+            types.Tool(name="reindex", description="Run full or incremental indexing for a project", inputSchema=_tool_schema({"project": {"type": ["string", "null"]}, "full": {"type": "boolean"}})),
+            types.Tool(name="project_status", description="Return git and index status for a project", inputSchema=_tool_schema({"project": {"type": ["string", "null"]}})),
+            types.Tool(
+                name="search_context",
+                description=(
+                    "Semantic search over an indexed project. Returns the most relevant code chunks "
+                    "(file, symbol, signature, body) ranked by embedding + BM25 + cross-encoder reranker. "
+                    "Use this instead of reading files directly to get compacted, relevant context without wasting tokens."
+                ),
+                inputSchema=_tool_schema(
+                    {
+                        "query": {"type": "string"},
+                        "project": {"type": ["string", "null"]},
+                        "top_k": {"type": "integer", "default": 10},
+                    },
+                    ["query"],
+                ),
+            ),
+            types.Tool(
+                name="map_context",
+                description=(
+                    "Semantic map of codebase components relevant to a query. "
+                    "Returns ranked code chunks with their caller/callee relationships from the AST graph, "
+                    "a per-file symbol index, a dependency graph, and an optional LLM-synthesized narrative "
+                    "(local model only, zero remote cost) explaining how the components work together. "
+                    "Use this BEFORE analyze_request or before reading files directly — it gives Claude the "
+                    "architectural context needed to plan edits without re-reading the entire codebase."
+                ),
+                inputSchema=_tool_schema(
+                    {
+                        "query": {"type": "string"},
+                        "project": {"type": ["string", "null"]},
+                        "top_k": {"type": "integer", "default": 10},
+                        "include_bodies": {"type": "boolean", "default": True},
+                        "synthesize": {"type": "boolean", "default": True},
+                    },
+                    ["query"],
+                ),
+            ),
+            types.Tool(
+                name="generate_document",
+                description=(
+                    "Generate a file (e.g. Markdown, text) by retrieving relevant code context via semantic search "
+                    "and synthesizing it with an LLM. Use for tasks like 'create CORE_PIPELINE.md documenting the "
+                    "architecture' where analyze_request would fail because there is no existing code region to target. "
+                    "Writes the generated content to output_path (relative to the project root)."
+                ),
+                inputSchema=_tool_schema(
+                    {
+                        "prompt": {"type": "string"},
+                        "output_path": {"type": "string"},
+                        "project": {"type": ["string", "null"]},
+                        "top_k": {"type": "integer", "default": 15},
+                    },
+                    ["prompt", "output_path"],
+                ),
+            ),
+            types.Tool(
+                name="generate_business_logic",
+                description=(
+                    "Extract and document the current business logic of the active project from its repo state. "
+                    "Runs multiple semantic searches across domain models, rules, workflows, and entry points, "
+                    "then synthesizes a BUSINESS_LOGIC.md (or custom output_path) describing what the system does "
+                    "from a business perspective — entities, invariants, workflows, and external integrations. "
+                    "Overwrites the file if it already exists. Use this to get an up-to-date picture of the "
+                    "business domain whenever the codebase changes significantly."
+                ),
+                inputSchema=_tool_schema(
+                    {
+                        "project": {"type": ["string", "null"]},
+                        "output_path": {"type": "string", "default": "BUSINESS_LOGIC.md"},
+                        "top_k": {"type": "integer", "default": 20},
+                    },
+                ),
+            ),
+            types.Tool(
+                name="list_snippets",
+                description=(
+                    "List available snippets in the snippet library. "
+                    "Filter by framework (nest, fastapi, flutter, cmake, laravel, axum, aspnetcore, spring), "
+                    "language (typescript, python, dart, c, php, rust, csharp, java) "
+                    "or layer (domain, application, infrastructure, interface)."
+                ),
+                inputSchema=_tool_schema(
+                    {
+                        "framework": {"type": ["string", "null"]},
+                        "language": {"type": ["string", "null"]},
+                        "layer": {"type": ["string", "null"]},
+                    }
+                ),
+            ),
+            types.Tool(
+                name="init_project",
+                description=(
+                    "Scan a directory and register it as a new project in the codepreproc registry. "
+                    "Uses the session root (i.e. the directory Claude Code is open in) when no path is given. "
+                    "Does nothing if the project is already registered. "
+                    "After success, call reindex to build the index."
+                ),
+                inputSchema=_tool_schema({"path": {"type": ["string", "null"]}}),
+            ),
+            types.Tool(
+                name="assemble_from_snippets",
+                description=(
+                    "Two-phase DDD code generation from the snippet library. "
+                    "Phase 1 (low-cost model): resolves intent, selects snippets, binds variables, defines scope. "
+                    "Phase 2 (high-capability model): integrates instantiated snippets into target files. "
+                    "Produces files_created and files_modified respecting DDD layer boundaries. "
+                    "Use for creating new CRUD modules from scratch, not for modifying existing code regions."
+                ),
+                inputSchema=_tool_schema(
+                    {
+                        "prompt": {"type": "string"},
+                        "project": {"type": ["string", "null"]},
+                    },
+                    ["prompt"],
+                ),
+            ),
+            types.Tool(
+                name="generate_repo_map",
+                description=(
+                    "Generate a full hierarchical map of the repository. "
+                    "Builds a structured JSON with artifacts, packages, modules, components, "
+                    "interfaces, implementations, methods, properties, and relationships. "
+                    "For monorepos, auto-detects apps/ (artifacts) and packages/ (reusable modules); "
+                    "each direct subfolder of those is treated as a unit, and its src/ directory "
+                    "is the module root. If the layout is not detected, returns needs_clarification=true "
+                    "with questions to answer via artifacts_folder and modules_folder. "
+                    "Excludes .git from the scan. "
+                    "Stores the result in the knowledge graph and writes repo_map.json to the project root."
+                ),
+                inputSchema=_tool_schema({
+                    "project": {"type": ["string", "null"]},
+                    "artifacts_folder": {"type": ["string", "null"], "description": "Top-level folder that contains deployable apps/artifacts (e.g. 'apps')."},
+                    "modules_folder": {"type": ["string", "null"], "description": "Top-level folder that contains reusable shared modules (e.g. 'packages')."},
+                }),
+            ),
+            types.Tool(
+                name="kg_context",
+                description=(
+                    "Retrieve SuperKG context for a project in a specific reasoning mode. "
+                    "Modes: narrative (story/explanation), reflexive (self-analysis), "
+                    "comparative (cross-system), consolidation (aggregation), simulation (scenario projection). "
+                    "Use this to get persistent knowledge and insights about the project from SuperKG."
+                ),
+                inputSchema=_tool_schema(
+                    {
+                        "project": {"type": ["string", "null"]},
+                        "mode": {
+                            "type": "string",
+                            "enum": ["narrative", "reflexive", "comparative", "consolidation", "simulation"],
+                            "default": "narrative",
+                        },
+                    },
+                ),
+            ),
+            types.Tool(
+                name="kg_insights",
+                description="List insights stored in SuperKG for a project.",
+                inputSchema=_tool_schema({"project": {"type": ["string", "null"]}}),
+            ),
+            types.Tool(
+                name="kg_patterns",
+                description="List observed patterns across all projects in SuperKG.",
+                inputSchema=_tool_schema({}),
+            ),
+            types.Tool(
+                name="project_pseudocode",
+                description=(
+                    "Return the entire indexed project as typed pseudo-code: every file with its symbols "
+                    "(classes, functions, methods) and their type signatures. "
+                    "Signature-only mode (default) reads only the SQLite AST graph — zero LLM cost, sub-second. "
+                    "Set include_bodies=true to also fetch full source bodies from Qdrant, ordered by line. "
+                    "Use file_pattern (e.g. 'src/**/*.py') to scope to a subtree. "
+                    "Gives Claude a project-wide typed interface view without reading individual files."
+                ),
+                inputSchema=_tool_schema(
+                    {
+                        "project": {"type": ["string", "null"]},
+                        "file_pattern": {"type": ["string", "null"], "description": "Glob to filter files, e.g. 'src/**/*.py'"},
+                        "include_bodies": {"type": "boolean", "default": False},
+                        "exclude_tests": {"type": "boolean", "default": True},
+                        "max_files": {"type": "integer", "default": 200},
+                    }
+                ),
+            ),
+            types.Tool(
+                name="correct_graph",
+                description=(
+                    "Submit a human-authored Business Logic Diff to correct the SuperKG knowledge graph. "
+                    "Use when the graph state diverges from truth — e.g. after a manual change outside "
+                    "codepreproc. Express the correction as before/after rule lists, not direct node/edge "
+                    "edits, so it is auditable through the same writer as the automatic patch path."
+                ),
+                inputSchema=_tool_schema(
+                    {
+                        "change": {"type": "string", "description": "Short identifier for this correction (e.g. 'remove-email-uniqueness-check')"},
+                        "before": {"type": "array", "items": {"type": "string"}, "description": "Current rules/capabilities as they exist in the graph"},
+                        "after": {"type": "array", "items": {"type": "string"}, "description": "Target rules/capabilities after this correction"},
+                        "rules_added": {"type": "array", "items": {"type": "string"}},
+                        "rules_removed": {"type": "array", "items": {"type": "string"}},
+                        "rules_modified": {"type": "array", "items": {"type": "string"}},
+                        "project": {"type": ["string", "null"]},
+                    },
+                    ["change"],
+                ),
+            ),
+            types.Tool(
+                name="coupling_project",
+                description=(
+                    "Project the cross-repo coupling structure for a set of registered repositories in ONE call. "
+                    "Returns a compact summary with: symbol table (project ids), edge list (src→dst with counts), "
+                    "Ca/Ce/instability metrics per pair, and non-trivial SCCs (dependency cycles between repos). "
+                    "The full edge set is stored in-memory behind a handle; use coupling_expand to retrieve detail. "
+                    "Prefer anchors (concrete project_id list) over intent (fuzzy text → resolved to project set). "
+                    "Operators: anchors=[id,...] for structural query; intent='...' for fuzzy; "
+                    "coupling_expand(handle_id, edge_id) for per-edge detail."
+                ),
+                inputSchema=_tool_schema(
+                    {
+                        "anchors": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "List of registered project_ids to include in the coupling projection.",
+                        },
+                        "intent": {
+                            "type": ["string", "null"],
+                            "description": "Fuzzy description resolved to a project set when anchors is empty.",
+                        },
+                    },
+                ),
+            ),
+            types.Tool(
+                name="coupling_expand",
+                description=(
+                    "Expand a coupling handle returned by coupling_project to retrieve edge detail on demand. "
+                    "With edge_id: returns full ResolutionEdge detail (src/dst symbols, file paths, epoch). "
+                    "Without edge_id: returns a paginated list of edges for the handle."
+                ),
+                inputSchema=_tool_schema(
+                    {
+                        "handle_id": {"type": "string", "description": "Handle returned by coupling_project."},
+                        "edge_id": {"type": ["string", "null"], "description": "UUID of a specific edge to expand."},
+                        "offset": {"type": "integer", "default": 0},
+                        "limit": {"type": "integer", "default": 50},
+                    },
+                    ["handle_id"],
+                ),
+            ),
+        ]
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict | None) -> types.CallToolResult:
+        session = server.request_context.session
+        request_context = server.request_context
+        state = sessions.setdefault(id(session), SessionState())
+        root_uris = await resolve_session_roots(
+            session=session,
+            lifecycle_logger=lifecycle_logger,
+            request_id=request_context.request_id,
+        )
+        if root_uris:
+            state.roots = [_path_from_file_uri(uri) for uri in root_uris]
+        else:
+            state.roots = state.roots or []
+
+        dispatch = {
+            "list_projects": lambda monitor: tools.list_projects(state),
+            "switch_project": lambda monitor: tools.switch_project(state, arguments or {}),
+            "analyze_request": lambda monitor: tools.analyze_request(state, arguments or {}, monitor=monitor),
+            "analyze_filesystem_reorg": lambda monitor: tools.analyze_filesystem_reorg(state, arguments or {}, monitor=monitor),
+            "preview_semantic_plan": lambda monitor: tools.preview_semantic_plan(state, arguments or {}),
+            "preview_filesystem_plan": lambda monitor: tools.preview_filesystem_plan(state, arguments or {}),
+            "preview_patch": lambda monitor: tools.preview_patch(state, arguments or {}),
+            "validate_patch": lambda monitor: tools.validate_patch(state, arguments or {}),
+            "disambiguate_region": lambda monitor: tools.disambiguate_region(state, arguments or {}),
+            "apply_patch": lambda monitor: tools.apply_patch(state, arguments or {}),
+            "apply_filesystem_plan": lambda monitor: tools.apply_filesystem_plan(state, arguments or {}, monitor=monitor),
+            "usage_report": lambda monitor: tools.usage_report(state, arguments or {}),
+            "set_llm_policy": lambda monitor: tools.set_llm_policy(state, arguments or {}),
+            "reindex": lambda monitor: tools.reindex(state, arguments or {}, monitor=monitor),
+            "project_status": lambda monitor: tools.project_status(state, arguments or {}),
+            "search_context": lambda monitor: tools.search_context(state, arguments or {}, monitor=monitor),
+            "map_context": lambda monitor: tools.map_context(state, arguments or {}, monitor=monitor),
+            "generate_document": lambda monitor: tools.generate_document(state, arguments or {}, monitor=monitor),
+            "generate_business_logic": lambda monitor: tools.generate_business_logic(state, arguments or {}, monitor=monitor),
+            "list_snippets": lambda monitor: tools.list_snippets(state, arguments or {}),
+            "assemble_from_snippets": lambda monitor: tools.assemble_from_snippets(state, arguments or {}, monitor=monitor),
+            "init_project": lambda monitor: tools.init_project(state, arguments or {}),
+            "generate_repo_map": lambda monitor: tools.generate_repo_map(state, arguments or {}, monitor=monitor),
+            "kg_context": lambda monitor: tools.kg_context(state, arguments or {}),
+            "kg_insights": lambda monitor: tools.kg_insights(state, arguments or {}),
+            "kg_patterns": lambda monitor: tools.kg_patterns(state, arguments or {}),
+            "correct_graph": lambda monitor: tools.correct_graph(state, arguments or {}),
+            "project_pseudocode": lambda monitor: tools.project_pseudocode(state, arguments or {}),
+            "coupling_project": lambda monitor: tools.coupling_project(state, arguments or {}, monitor=monitor),
+            "coupling_expand": lambda monitor: tools.coupling_expand(state, arguments or {}),
+        }
+        if name not in dispatch:
+            raise ValueError(f"unknown_tool: {name}")
+        monitor = ActionMonitor(
+            session=session,
+            logger=logger,
+            tool=name,
+            request_id=request_context.request_id,
+            progress_token=request_context.meta.progressToken if request_context.meta else None,
+            timeout_seconds=settings.defaults.mcp_action_timeout_seconds,
+            heartbeat_seconds=settings.defaults.mcp_action_heartbeat_seconds,
+            project=(arguments or {}).get("project"),
+        )
+        try:
+            await monitor.start(f"{name}: iniciando")
+            result = await dispatch[name](monitor)
+            await monitor.complete(f"{name}: completado")
+            return types.CallToolResult(
+                content=[types.TextContent(type="text", text=json.dumps(result, ensure_ascii=False))],
+                structuredContent=result,
+                isError=False,
+            )
+        except asyncio.CancelledError as exc:
+            timeout_error = monitor.timeout_error()
+            if timeout_error is None:
+                raise
+            payload = timeout_error.to_payload(tool=name, stage=timeout_error.details.get("stage"))
+            await monitor.fail(payload["message"], stage=payload["details"].get("stage"), details=payload["details"])
+            return types.CallToolResult(
+                content=[types.TextContent(type="text", text=json.dumps(payload, ensure_ascii=False))],
+                structuredContent=payload,
+                isError=True,
+            )
+        except ToolExecutionError as exc:
+            payload = exc.to_payload(tool=name, stage=exc.details.get("stage"))
+            await monitor.fail(payload["message"], stage=payload["details"].get("stage"), details=payload["details"])
+            return types.CallToolResult(
+                content=[types.TextContent(type="text", text=json.dumps(payload, ensure_ascii=False))],
+                structuredContent=payload,
+                isError=True,
+            )
+        except Exception as exc:
+            logger.exception("Tool error in %s", name)
+            error_payload = {
+                "error": "tool_failed",
+                "message": str(exc)[:500],
+                "details": {
+                    "tool": name,
+                    "stage": monitor.stage_name,
+                    "idle_seconds": int(max(0, time.monotonic() - monitor.last_relevant_change_at)),
+                    "last_progress": monitor.last_progress,
+                },
+            }
+            await monitor.fail(error_payload["message"], stage=monitor.stage_name, details=error_payload["details"])
+            return types.CallToolResult(
+                content=[types.TextContent(type="text", text=json.dumps(error_payload, ensure_ascii=False))],
+                structuredContent=error_payload,
+                isError=True,
+            )
+        finally:
+            await monitor.close()
+
+    version = importlib.metadata.version("codepreproc")
+    try:
+        async with stdio_server() as (read_stream, write_stream):
+            await server.run(
+                read_stream,
+                write_stream,
+                InitializationOptions(
+                    server_name="codepreproc",
+                    server_version=version,
+                    capabilities=ServerCapabilities(tools=ToolsCapability(listChanged=False)),
+                ),
+            )
+    finally:
+        await llm_runtime.close()
+        await _db.close_pool()
+
+
+def run() -> None:
+    """Console script entrypoint."""
+
+    anyio.run(main)