marvisx-cli 0.1.0__py3-none-any.whl

core/api/mcp/tools/ingest.py

@@ -0,0 +1,326 @@
+# v1.0.0 - 2026-05-27 - S1 F3.1d: ingest-triage MCP tool group (use_cases-direct, no HTTP)
+"""Ingest-triage MCP tools — port of the Node ``*_ingest*`` group, use_cases-direct.
+
+Same TEMPLATE as ``tasks.py`` / ``graph.py``: the Node HTTP proxy
+(``get``/``post``/``patch`` -> ``:8100``) is replaced by an in-process
+``await ingest_uc.<fn>(LOCAL_CTX, db, ...)`` against the read/write pool the
+tool acquires via ``acquire_db()`` / ``acquire_write_db()``. Docstrings are copied
+VERBATIM from ``core/mcp-pir/index.mjs`` (curated QUANDO USARLO / NON USARLO /
+RESTITUISCE blocks).
+
+Schema port (Zod -> Pydantic), per S1 F3:
+  * ``z.enum([...])``            -> ``Literal[...]``
+  * ``z.string().uuid()``        -> ``Annotated[str, Field(pattern=_UUID_PATTERN)]``
+  * ``z.string().regex(slug)``   -> ``Annotated[str, Field(pattern=_PROJECT_SLUG_PATTERN)]``
+  * ``z.number().int().min().max()`` -> ``Annotated[int, Field(ge=, le=)]``
+  * ``z.record(z.string(), z.string())`` -> ``dict[str, str] | None``
+  * optional                     -> ``X | None = None`` (or ``= <default>``)
+
+Visibility: the MCP surface is local single-user (no ``UserInfo.teams``), so every
+tool passes ``visible_projects=None`` = unrestricted (the same DECISION 1 the
+use_cases / the other groups take). ``LOCAL_CTX`` is ``operator`` so the
+operator+ ``require_role_ctx`` gates inside the use_cases pass.
+
+FIRE-AND-FORGET SCHEDULING is NOT replicated here (DECISION). The use_cases perform
+the durable DB transition (the source of truth) and return; the HTTP adapter then
+schedules ``parse_pending`` / ``execute_saga`` (``asyncio.create_task``) and emits
+the ``broadcast_ingest_changed`` SSE notification. Both the parser/saga workers and
+the SSE channel are server-lifecycle / transport side-channels — the SAME
+per-surface trade-off the tasks template documents for ``mcp_schedule_embed`` (the
+auto-embed worker, S1 F4). Importing ``parse_pending`` / ``execute_saga`` /
+``broadcast_ingest_changed`` here would ALSO drag fastapi into the MCP import path
+(they transitively import a fastapi module — the use_case keeps them FUNCTION-LOCAL
+for exactly this reason), so they are NOT imported. Net: ``approve`` /
+``reject`` / ``classify`` / ``reparse`` commit the row transition; the actual
+parse/saga execution is driven by the in-process worker wiring the server lifecycle
+owns (parity with the auto-embed F4 no-op).
+
+PATCH transport-boundary replication. ``patch_pending`` (the use_case) owns the
+sha-collision check, containment, atomic move, and the row + change-history writes;
+the HTTP adapter resolves the row + the destination input-root + the slug/path
+guards BEFORE calling it. The MCP ``patch_ingest_pending`` surface takes only
+``id`` + optional ``project_slug`` (Node parity), so this module replicates the
+ADAPTER pre-work locally, fastapi-free: load the row, no-op short-circuit on an
+unchanged/empty slug, slug-regex validate, and resolve the destination
+``input_root`` against ``PROJECTS_ROOT`` (the same constant the router uses;
+test-overridable via ``monkeypatch.setattr(ingest_tools, "PROJECTS_ROOT", ...)``).
+The bespoke ``HTTPException`` dict bodies the router raises are a transport contract
+the MCP surface does not carry — slug/path failures raise ``ValidationError`` /
+``NotFoundError`` (mapped via ``raise_mcp_error``).
+
+SKIPPED (no clean fastapi-free use_case):
+  * ``upload_ingest`` — there is NO ``upload`` function in
+    ``use_cases.ingest_triage``. The upload pipeline (MIME validation +
+    ``_save_upload_file`` + ``dispatch_files_batched``) lives ENTIRELY in
+    ``routers/ingest_triage.py`` + the ingest services, and ``dispatch_files_batched``
+    transitively imports fastapi. Porting would mean re-implementing the
+    router/service multipart+dispatch path, not calling a use_case — out of scope
+    for the use_cases-direct port (S1 F3 SKIP rule), so it is skipped, not faked.
+  * ``write_haiku_frontmatter`` — the HTTP endpoint is a router-only 501 placeholder
+    (``write_frontmatter_placeholder``); there is no ``use_cases.ingest_triage``
+    function and nothing to call. The Node tool documents "Pre-E5: 501". Skipped
+    until E5 extracts a use_case.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Annotated, Any, Literal
+
+from pydantic import Field
+
+from core.api.mcp._adapter import (
+    LOCAL_CTX,
+    acquire_db,
+    acquire_write_db,
+    dump,
+    raise_mcp_error,
+)
+from core.api.use_cases import ingest_triage as ingest_uc
+from core.api.use_cases._errors import NotFoundError, ServiceError, ValidationError
+
+# Zod enums -> Literals (mirror the Node tool signatures).
+IngestStatus = Literal[
+    "queued", "parsing", "classified", "awaiting_triage", "approved",
+    "inserted", "done", "parse_error", "rejected", "all",
+]
+
+# Node Zod patterns mirrored as Pydantic Field patterns.
+_UUID_PATTERN = (
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-"
+    r"[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+# index.mjs _PROJECT_SLUG_RE = /^[a-z0-9][a-z0-9_&-]+$/
+_PROJECT_SLUG_PATTERN = r"^[a-z0-9][a-z0-9_&-]+$"
+_PROJECT_SLUG_RE = re.compile(_PROJECT_SLUG_PATTERN)
+
+# The projects metadata root the patch file-move resolves against. Same constant
+# the router uses; module-level so a test can override it with
+# ``monkeypatch.setattr(ingest_tools, "PROJECTS_ROOT", tmp_path)``.
+PROJECTS_ROOT = Path("/data/projects").resolve()
+
+
+def _project_input_root(project_slug: str) -> Path:
+    """Resolve ``PROJECTS_ROOT/<slug>/input`` with the router's containment guards.
+
+    fastapi-free counterpart of the router's ``_project_input_root``: the bespoke
+    ``HTTPException`` dict bodies (``INVALID_SLUG_FORMAT`` / ``PROJECT_NOT_FOUND`` /
+    ``SLUG_PATH_TRAVERSAL``) are a transport contract the MCP surface does not carry,
+    so the same conditions raise ``ValidationError`` / ``NotFoundError`` (mapped via
+    ``raise_mcp_error``).
+    """
+    if not _PROJECT_SLUG_RE.fullmatch(project_slug):
+        raise ValidationError(
+            code="invalid_slug_format",
+            message=f"Project slug '{project_slug}' must match [a-z0-9][a-z0-9_&-]+",
+        )
+    project_root = (PROJECTS_ROOT / project_slug).resolve()
+    if not project_root.is_relative_to(PROJECTS_ROOT):
+        raise ValidationError(
+            code="slug_path_traversal",
+            message=f"Resolved path for '{project_slug}' escapes projects root",
+        )
+    if not project_root.is_dir():
+        raise NotFoundError(
+            code="project_not_found",
+            message=f"Project '{project_slug}' not found",
+        )
+    input_root = (project_root / "input").resolve()
+    if not input_root.is_relative_to(project_root):
+        raise ValidationError(
+            code="slug_path_traversal",
+            message="Input directory escapes project root",
+        )
+    return input_root
+
+
+def register(mcp) -> None:
+    """Register the ingest-triage tool group on the shared FastMCP instance."""
+
+    @mcp.tool()
+    async def list_ingest_pending(
+        status: IngestStatus | None = None,
+        project: Annotated[str, Field(pattern=_PROJECT_SLUG_PATTERN)] | None = None,
+        limit: Annotated[int, Field(ge=1, le=250)] = 50,
+    ) -> list[dict[str, Any]]:
+        """List ingest_pending rows con filtri status/project/limit. Phase 1.5 capability via MCP per agent.
+
+        QUANDO USARLO: serve la coda triage (queued/parsing/awaiting_triage/parse_error/...) per un progetto o globale (visibility-filtered).
+        QUANDO NON USARLO: NOT per dettaglio singolo row -> nessun get_ingest_pending dedicato; usa la list filtrata. NOT per cambiare stato -> approve/reject/patch.
+        RESTITUISCE: list of IngestPendingItem (id, file_path, project_slug, status, classification, target_folder, target_filename, ...)."""
+        # Node maps status="all" -> no status filter (drops the param). Local sees
+        # all projects (visible_projects=None), so project_filter_visible stays True.
+        try:
+            async with acquire_db() as db:
+                result = await ingest_uc.list_pending(
+                    LOCAL_CTX,
+                    db,
+                    status=None if status == "all" else status,
+                    project_slug=project,
+                    limit=limit,
+                    visible_projects=None,
+                )
+                return dump(result)
+        except ServiceError as e:
+            raise_mcp_error(e)
+
+    @mcp.tool()
+    async def approve_ingest_pending(
+        id: Annotated[str, Field(pattern=_UUID_PATTERN)],
+        classification_override: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Approve ingest_pending row → triggers saga move da input/ a target_folder + KG insert. Optional classification_override (logged decision_source=agent_override; backend support post-E5).
+
+        QUANDO USARLO: row in awaiting_triage con target_folder/target_filename validi → approval umano via agent.
+        QUANDO NON USARLO: NOT su row in stato diverso da awaiting_triage (409). NOT per cambiare project_slug -> usa patch_ingest_pending.
+        RESTITUISCE: {id, status:approved} dopo enqueue saga."""
+        # The use_case returns (response, project_slug); the second element feeds the
+        # HTTP adapter's SSE broadcast (a transport side-channel not replicated here,
+        # see module docstring). classification_override is accepted for Node parity
+        # but not forwarded — the use_case signature does not carry it (backend
+        # support is post-E5). The durable status='approved' transition commits here;
+        # the saga is driven by the server-lifecycle worker.
+        try:
+            async with acquire_write_db() as db:
+                response, _project_slug = await ingest_uc.approve(
+                    LOCAL_CTX, db, ingest_id=id, visible_projects=None,
+                )
+                return dump(response)
+        except ServiceError as e:
+            raise_mcp_error(e)
+
+    @mcp.tool()
+    async def reject_ingest_pending(
+        id: Annotated[str, Field(pattern=_UUID_PATTERN)],
+        reason: Annotated[str, Field(max_length=500)],
+    ) -> dict[str, Any]:
+        """Reject ingest_pending row → status=rejected, file resta orphan in input/.
+
+        QUANDO USARLO: row non vuole essere ingestita (low signal, duplicato, off-topic) → libera la coda triage.
+        QUANDO NON USARLO: NOT per cancellare il file fisico (resta orphan in input/). NOT per cambiare project_slug post-rejection -> patch_ingest_pending supporta lo stato rejected.
+        RESTITUISCE: {id, status:rejected}."""
+        # The use_case `reject` is a soft state transition and does not carry a
+        # `reason` arg (the Node `reason` is the HTTP body the legacy router
+        # accepted; the durable transition only records `triage_decision_id`).
+        # Accepted on the surface for Node parity. Returns (response, project_slug).
+        try:
+            async with acquire_write_db() as db:
+                response, _project_slug = await ingest_uc.reject(
+                    LOCAL_CTX, db, ingest_id=id, visible_projects=None,
+                )
+                return dump(response)
+        except ServiceError as e:
+            raise_mcp_error(e)
+
+    @mcp.tool()
+    async def patch_ingest_pending(
+        id: Annotated[str, Field(pattern=_UUID_PATTERN)],
+        project_slug: Annotated[str, Field(pattern=_PROJECT_SLUG_PATTERN)] | None = None,
+    ) -> dict[str, Any]:
+        """Change project_slug post-upload (E4). State machine: SOLO awaiting_triage/parse_error/rejected. Atomic copy-then-rename con path containment.
+
+        QUANDO USARLO: file finito nel progetto sbagliato in upload → reroute prima dell'approve.
+        QUANDO NON USARLO: NOT su row in flight (queued/parsing/approved/inserted/done) -> 422. NOT per cambiare classification (target_folder/filename) -> richiede E4 follow-up non ancora live.
+        RESTITUISCE: IngestPendingItem aggiornato."""
+        # Replicate the router's transport-boundary pre-work fastapi-free (load row,
+        # state guard, no-op short-circuit, slug validate, input_root resolve), then
+        # hand the resolved Path objects to the use_case which owns the domain truth
+        # (sha-collision, containment, atomic move, row + change-history writes).
+        try:
+            async with acquire_write_db() as db:
+                row = await ingest_uc._load_row(db, id)
+
+                allowed_states = ("awaiting_triage", "parse_error", "rejected")
+                if row["status"] not in allowed_states:
+                    raise ValidationError(
+                        code="invalid_state_for_change",
+                        message=(
+                            f"Item state '{row['status']}' is not patchable "
+                            f"(allowed: {', '.join(allowed_states)})"
+                        ),
+                    )
+
+                new_slug = project_slug
+                if not new_slug or new_slug == row["project_slug"]:
+                    # No-op: return the current row so the caller can refresh.
+                    return dump(ingest_uc._row_to_item(row))
+
+                new_input_root = _project_input_root(new_slug)
+                result = await ingest_uc.patch_pending(
+                    LOCAL_CTX,
+                    db,
+                    row=row,
+                    new_slug=new_slug,
+                    new_input_root=new_input_root,
+                    projects_root=PROJECTS_ROOT,
+                    changed_by=LOCAL_CTX.username,
+                    source_ip=None,
+                    user_agent="mcp-local",
+                )
+                return dump(result)
+        except ServiceError as e:
+            raise_mcp_error(e)
+
+    @mcp.tool()
+    async def classify_ingest(
+        id: Annotated[str, Field(pattern=_UUID_PATTERN)],
+        force: bool = False,
+    ) -> dict[str, Any]:
+        """Force re-classify ingest_pending row. Phase 1 = deterministic re-parse (parser_router); post P1.5.E5 = trigger Haiku #1 manuale senza cambi MCP/UI.
+
+        QUANDO USARLO: classification originale era sbagliata e vuoi rilanciare il classifier (es. dopo training data update).
+        QUANDO NON USARLO: NOT per parse_error (usa reparse_ingest che e' lo stesso path semanticamente). NOT su done/inserted (409 stato non valido).
+        RESTITUISCE: {id, status:parsing}."""
+        # `force` is accepted for Node parity; the Node handler ignores it too (it
+        # always POSTs classify-force). The durable status='queued' reset commits
+        # here; the deterministic re-parse is driven by the server-lifecycle worker.
+        try:
+            async with acquire_write_db() as db:
+                result = await ingest_uc.classify_force(
+                    LOCAL_CTX, db, ingest_id=id, visible_projects=None,
+                )
+                return dump(result)
+        except ServiceError as e:
+            raise_mcp_error(e)
+
+    @mcp.tool()
+    async def reparse_ingest(
+        id: Annotated[str, Field(pattern=_UUID_PATTERN)] | None = None,
+        status: Literal["parse_error"] | None = None,
+    ) -> dict[str, Any]:
+        """Re-parse ingest_pending row (single id) o batch (status=parse_error, admin only). Riusa parser_router via API invece di scripts/reparse_failed.py.
+
+        QUANDO USARLO: row in parse_error → ritenta dopo fix parser/dipendenze. Batch utile per recovery post-deploy.
+        QUANDO NON USARLO: NOT con id E status insieme (usa uno o l'altro). NOT per cambiare project_slug -> patch_ingest_pending.
+        RESTITUISCE: single → {id, status:parsing}; batch → {queued_count, status}."""
+        if id and status:
+            raise_mcp_error(
+                ValidationError(
+                    code="reparse_args_conflict",
+                    message="Provide id OR status, not both",
+                )
+            )
+        try:
+            if id:
+                async with acquire_write_db() as db:
+                    result = await ingest_uc.reparse_single(
+                        LOCAL_CTX, db, ingest_id=id, visible_projects=None,
+                    )
+                    return dump(result)
+            if status:
+                # The batch read selects the matching ids; the use_case returns
+                # (response, ids). The per-row parse fan-out is the server-lifecycle
+                # worker's job (not replicated here, see module docstring).
+                async with acquire_db() as db:
+                    response, _ids = await ingest_uc.reparse_batch(
+                        LOCAL_CTX, db, target_status=status, visible_projects=None,
+                    )
+                    return dump(response)
+            raise_mcp_error(
+                ValidationError(
+                    code="reparse_args_missing",
+                    message="Either id or status required",
+                )
+            )
+        except ServiceError as e:
+            raise_mcp_error(e)

core/api/mcp/tools/learnings.py

@@ -0,0 +1,144 @@
+# v1.0.0 - 2026-05-27 - S1 F3.0: learnings MCP tool group (use_cases-direct, no HTTP)
+"""Learnings MCP tools — port of the Node ``learnings`` group, use_cases-direct.
+
+Same template as ``tasks.py``: the Node HTTP proxy is replaced by an in-process
+``await learnings_uc.<action>(LOCAL_CTX, db, ...)``. Docstrings copied
+VERBATIM from ``core/mcp-pir/index.mjs``.
+
+Schema notes:
+  * ``check_learnings`` keeps the Node param name ``q`` (the surface contract);
+    the use_case parameter is ``query`` — mapped in the body. ``module`` optional.
+  * ``create_learning`` mirrors the Node REQUIRED set (title/category/description/
+    prevention/severity) and the optional set (module/tags/project). Enums become
+    ``Literal[...]``.
+
+Return typing: reads return ``dict[str, Any]`` / ``list[dict]``; ``create_learning``
+(mutator) returns the DTO ``.model_dump()`` via ``dump()``. visible_projects=None
+(local single-user, unrestricted).
+"""
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import Field
+
+from core.api.mcp._adapter import LOCAL_CTX, acquire_db, acquire_write_db, dump, raise_mcp_error
+from core.api.use_cases import learnings as learnings_uc
+from core.api.use_cases._errors import ServiceError
+
+LearningCategory = Literal[
+    "deploy", "migration", "auth", "testing", "architecture", "security", "performance"
+]
+LearningSeverity = Literal["low", "medium", "high", "critical"]
+
+
+def register(mcp) -> None:
+    """Register the learnings tool group on the shared FastMCP instance."""
+
+    @mcp.tool()
+    async def check_learnings(
+        q: Annotated[str, Field(min_length=1, max_length=500)],
+        module: str | None = None,
+    ) -> dict[str, Any]:
+        """Search learnings DB (past post-mortems + prevention rules) for a risky action.
+
+        QUANDO USARLO: PRIMA di qualunque azione production-affecting (deploy, migration, auth change, push to main, dependency upgrade) — Quality Gate 9.4. BOUNDARY: create_learning vs check_learnings = create scrive nuovo; check cerca rilevante PRE-azione rischiosa. BOUNDARY: check_learnings vs list_learnings = check = semantic match su situazione; list = enumerazione filtrata.
+        QUANDO NON USARLO: NOT quando hai gia' un file/module path e vuoi learnings scoped -> usa graph_pattern. NOT per scrivere un nuovo learning -> usa create_learning.
+        RESTITUISCE: list of {id, title, prevention, severity, module} ranked per rilevanza."""
+        try:
+            async with acquire_db() as db:
+                # Node param `q` -> use_case param `query`.
+                result = await learnings_uc.check_learnings(
+                    LOCAL_CTX, db, query=q, module=module
+                )
+                return dump(result)
+        except ServiceError as e:
+            raise_mcp_error(e)
+
+    @mcp.tool()
+    async def create_learning(
+        title: Annotated[str, Field(min_length=1, max_length=200)],
+        category: LearningCategory,
+        description: Annotated[str, Field(min_length=1)],
+        prevention: Annotated[str, Field(min_length=1)],
+        severity: LearningSeverity,
+        module: str | None = None,
+        tags: list[str] | None = None,
+        project: str | None = None,
+    ) -> dict[str, Any]:
+        """Persist a new learning (post-mortem) with prevention rule after an error or incident.
+
+        QUANDO USARLO: DOPO aver hit un bug che vale la pena ricordare cross-session (es. 'z.record(1-arg) crashes MCP SDK'). BOUNDARY: create_learning vs check_learnings = create scrive nuovo; check cerca rilevante PRE-azione rischiosa.
+        QUANDO NON USARLO: NOT per idea forward-looking improvement -> usa create_task kind='idea'. NOT per task operativo -> usa create_task.
+        RESTITUISCE: {id, title, category, severity, created_at} — indexed by check_learnings."""
+        try:
+            async with acquire_write_db(label="mcp.create_learning") as db:
+                result = await learnings_uc.create_learning(
+                    LOCAL_CTX,
+                    db,
+                    title=title,
+                    category=category,
+                    description=description,
+                    prevention=prevention,
+                    severity=severity,
+                    module=module,
+                    tags=tags,
+                    project=project,
+                )
+                return dump(result)
+        except ServiceError as e:
+            raise_mcp_error(e)
+
+    @mcp.tool()
+    async def list_learnings(
+        project: str | None = None,
+        category: LearningCategory | None = None,
+        severity: LearningSeverity | None = None,
+        tags: str | None = None,
+        search: str | None = None,
+        limit: Annotated[int, Field(ge=1, le=200)] = 50,
+        offset: Annotated[int, Field(ge=0)] = 0,
+    ) -> list[dict[str, Any]]:
+        """List learnings with optional filters (category, project, severity, tags, free text).
+
+        QUANDO USARLO: enumerare tutti i learning del progetto o filtrare per category/severity/tags. Utile per review periodica pattern consolidati. BOUNDARY: check_learnings vs list_learnings = check = semantic match su situazione; list = enumerazione filtrata.
+        QUANDO NON USARLO: NOT per cercare learning applicabile a situazione rischiosa corrente -> usa check_learnings (semantic). NOT per singolo ID -> usa get_learning.
+        RESTITUISCE: list of {id, title, category, severity, module, project, created_at, tags} paginato ordered per frequency DESC."""
+        try:
+            async with acquire_db() as db:
+                result = await learnings_uc.list_learnings(
+                    LOCAL_CTX,
+                    db,
+                    category=category,
+                    project=project,
+                    severity=severity,
+                    tags=tags,
+                    search=search,
+                    limit=limit,
+                    offset=offset,
+                    visible_projects=None,
+                )
+                return dump(result)
+        except ServiceError as e:
+            raise_mcp_error(e)
+
+    @mcp.tool()
+    async def get_learning(
+        learning_id: Annotated[str, Field(min_length=1)],
+        deep: bool | None = None,
+    ) -> dict[str, Any]:
+        """Get a single learning by UUID.
+
+        QUANDO USARLO: hai un learning ID (da list_learnings o check_learnings) e vuoi il body completo (description + prevention + tags). Usa ?deep=true per includere kg_context inline (context chain, related learnings) — risparmia 2-3 tool call aggiuntivi.
+        QUANDO NON USARLO: NOT per ricerca semantica pre-azione -> usa check_learnings. NOT per enumerazione filtrata -> usa list_learnings.
+        RESTITUISCE: {id, title, category, description, prevention, severity, tags, module, project, session, created_at, updated_at, frequency, last_occurrence} + kg_context se deep=true."""
+        try:
+            async with acquire_db() as db:
+                # DECISION 2: deep KG enrichment is an adapter concern; core fetch
+                # here, deep-attach lands in a later F3 increment.
+                result = await learnings_uc.get_learning(
+                    LOCAL_CTX, db, learning_id=learning_id
+                )
+                return dump(result)
+        except ServiceError as e:
+            raise_mcp_error(e)

core/api/mcp/tools/projects.py

@@ -0,0 +1,99 @@
+# v1.0.0 - 2026-05-27 - S1 F3.1a: projects MCP tool group (use_cases-direct, no HTTP)
+"""Projects MCP tools — port of the Node ``projects`` group, use_cases-direct.
+
+Same template as ``tasks.py`` / ``learnings.py``: the Node HTTP proxy
+(``get(/api/v1/projects...)``) is replaced by an in-process
+``await projects_uc.<action>(LOCAL_CTX, db, ...)``. Docstrings copied VERBATIM
+from ``core/mcp-pir/index.mjs``.
+
+Name mapping (Node tool name -> use_case function):
+  * ``list_projects``  -> ``projects_uc.list_programs`` (the Node tool returns the
+    project list grouped by program — that IS ``list_programs`` here).
+  * ``get_project``    -> ``projects_uc.get_project``.
+  * ``session_brief``  -> ``projects_uc.get_session_brief``.
+
+Deep KG enrichment is DEFERRED (same as F3.0): ``get_project`` returns the core
+fetch with ``kg_context=None`` and ignores ``deep`` (adapter concern, later F3
+increment). ``session_brief``'s ``get_session_brief`` assembles kg_context inside
+the use_case as part of the bundle contract — Node always cold-starts deep, so the
+MCP surface passes ``deep=True`` to widen the per-bucket KG limits (Node
+``effectiveDeep`` default).
+
+Return typing: reads return ``dict[str, Any]`` / ``list[dict]`` via ``dump()``
+(DTO lists are normalised element-wise). visible_projects=None (local single-user,
+unrestricted — DECISION 1).
+"""
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from pydantic import Field
+
+from core.api.mcp._adapter import LOCAL_CTX, acquire_db, dump, raise_mcp_error
+from core.api.use_cases import projects as projects_uc
+from core.api.use_cases._errors import ServiceError
+
+
+def register(mcp) -> None:
+    """Register the projects tool group on the shared FastMCP instance."""
+
+    @mcp.tool()
+    async def list_projects() -> list[dict[str, Any]]:
+        """List all PiR-tracked projects grouped by program.
+
+        QUANDO USARLO: serve un inventario (quali progetti ci sono, dammi tutti gli slug) o non conosci lo slug target.
+        QUANDO NON USARLO: NOT quando hai gia' uno slug specifico e vuoi i dettagli -> usa get_project. NOT per cold-start di un progetto -> usa session_brief.
+        RESTITUISCE: list of {slug, program, lifecycle, language, task_counts} senza body di context.md."""
+        try:
+            async with acquire_db() as db:
+                # Node `list_projects` returns the program-grouped project list =
+                # `list_programs` here. visible_projects=None -> local sees all.
+                result = await projects_uc.list_programs(
+                    LOCAL_CTX, db, visible_projects=None
+                )
+                return dump(result)
+        except ServiceError as e:
+            raise_mcp_error(e)
+
+    @mcp.tool()
+    async def get_project(
+        slug: Annotated[str, Field(min_length=1, max_length=50)],
+        deep: bool | None = None,
+    ) -> dict[str, Any]:
+        """Get full project detail (metadata + context.md body + handoff index + docs).
+
+        QUANDO USARLO: hai uno slug noto e ti serve lo stato raw del progetto (es. leggere context.md body o elenco handoff completo). Usa ?deep=true per includere kg_context inline (neighbors, context_chain, applicable_learnings) — risparmia 2-3 tool call aggiuntivi.
+        QUANDO NON USARLO: NOT per agent cold-start -> usa session_brief (aggrega project + open tasks + top learnings + salience docs in una call). NOT se non hai lo slug -> usa list_projects.
+        RESTITUISCE: {slug, metadata, context_md, handoffs[], docs[], deploy_info} + kg_context se deep=true."""
+        try:
+            async with acquire_db() as db:
+                # DECISION 2: `deep` KG enrichment is an adapter concern; the
+                # use_case returns kg_context=None (core fetch). The deep-attach
+                # is a later F3 increment, same as get_task/get_learning in F3.0.
+                result = await projects_uc.get_project(
+                    LOCAL_CTX, db, slug=slug, visible_projects=None
+                )
+                return dump(result)
+        except ServiceError as e:
+            raise_mcp_error(e)
+
+    @mcp.tool()
+    async def session_brief(
+        slug: Annotated[str, Field(min_length=1, max_length=50)],
+    ) -> dict[str, Any]:
+        """Cold-start aggregated context bundle for agent session resume.
+
+        QUANDO USARLO: inizio sessione su un progetto (sostituisce la sequenza get_project + list_tasks + search_handoffs + Read context.md + check_learnings). BOUNDARY: session_brief = cold-start aggregato; list_tasks+list_handoffs = query mirate.
+        QUANDO NON USARLO: NOT se ti serve solo il body grezzo di context.md o l'elenco completo handoff -> usa get_project. NOT per query filtrate puntuali -> usa list_tasks/list_handoffs.
+        RESTITUISCE: {project, open_tasks[], latest_handoff, recent_learnings[], top_salience_docs[]} tuned per context window LLM."""
+        try:
+            async with acquire_db() as db:
+                # The bundle's kg_context is part of the contract (assembled inside
+                # the use_case, not deferred). Node cold-starts deep by default
+                # (`effectiveDeep` -> true), so widen the per-bucket KG limits.
+                result = await projects_uc.get_session_brief(
+                    LOCAL_CTX, db, slug=slug, deep=True, visible_projects=None
+                )
+                return dump(result)
+        except ServiceError as e:
+            raise_mcp_error(e)