@heytherevibin/skillforge 0.2.1 → 0.7.0

package/python/app/mcp_contract.py

@@ -0,0 +1,121 @@
+"""Shared MCP response shape for ``route_skills`` (and CLI parity).
+
+Versioned ``_meta`` with ``sources[]`` and ``budget``. Schema **1.1** adds
+per-chunk ``sources`` when ``context_items`` (RAG chunks) are returned from Phase 1.
+Schema **1.2** adds ``kind: file`` sources and project chunk char counts in ``budget``.
+Schema **1.4** adds optional ``context_redaction`` (hit counts when scrubbing is on).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping, Protocol
+
+from app.redaction import redaction_enabled, redact_display_path
+
+
+class _SkillBody(Protocol):
+    name: str
+    body: str
+
+
+MCP_RESPONSE_SCHEMA_VERSION = "1.4"
+
+
+def build_route_skills_meta(
+    *,
+    result: dict[str, Any],
+    picked_names: list[str],
+    user_id: str,
+    db_path: Path | str,
+    skills_map: Mapping[str, _SkillBody],
+    response_text: str,
+    error: str | None = None,
+    context_items: list[dict[str, Any]] | None = None,
+    fusion: dict[str, Any] | None = None,
+    context_redaction: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build ``_meta`` for a route_skills-style response (success or structured error)."""
+    sources: list[dict[str, Any]] = []
+    chars_skill = 0
+    chars_project = 0
+
+    if context_items:
+        for c in context_items:
+            tlen = len(c.get("text") or "")
+            ref_path = c.get("path")
+            if ref_path:
+                row = {
+                    "kind": "file",
+                    "ref": ref_path,
+                    "line_start": c.get("line_start"),
+                    "line_end": c.get("line_end"),
+                    "score": round(float(c.get("score", 0.0)), 6),
+                }
+                if c.get("mmr_rank") is not None:
+                    row["mmr_rank"] = int(c["mmr_rank"])
+                sources.append(row)
+                chars_project += tlen
+            else:
+                row = {
+                    "kind": "skill",
+                    "ref": c["skill"],
+                    "line_start": c.get("line_start"),
+                    "line_end": c.get("line_end"),
+                    "score": round(float(c.get("score", 0.0)), 6),
+                }
+                if c.get("mmr_rank") is not None:
+                    row["mmr_rank"] = int(c["mmr_rank"])
+                sources.append(row)
+                chars_skill += tlen
+    else:
+        for n in picked_names:
+            s = skills_map.get(n)
+            if s is not None:
+                sources.append({
+                    "kind": "skill",
+                    "ref": n,
+                    "line_start": None,
+                    "line_end": None,
+                    "score": None,
+                })
+                chars_skill += len(s.body)
+
+    chars_body = chars_skill + chars_project
+
+    candidates_raw = result.get("candidates") or []
+    candidates_preview: list[dict[str, Any]] = []
+    for item in candidates_raw[:15]:
+        if isinstance(item, tuple) and len(item) == 2:
+            sk, sc = item
+            name = getattr(sk, "name", None)
+            if name is not None:
+                candidates_preview.append({"name": name, "score": round(float(sc), 6)})
+
+    meta: dict[str, Any] = {
+        "schema_version": MCP_RESPONSE_SCHEMA_VERSION,
+        "sources": sources,
+        "budget": {
+            "chars_skill_bodies": chars_skill,
+            "chars_project_chunks": chars_project,
+            "chars_context_items_total": chars_body,
+            "chars_response_total": len(response_text),
+            "est_tokens_approx": max(1, len(response_text) // 4),
+        },
+        "picked": list(picked_names),
+        "reasoning": result.get("reasoning"),
+        "session_id": result.get("session_id"),
+        "user_id": user_id,
+        "rerouted": result.get("rerouted"),
+        "change_pct": round(float(result.get("change", 0)) * 100, 1),
+        "route_ms": round(float(result.get("route_ms", 0)), 1),
+        "orchestrator_db": redact_display_path(db_path) if redaction_enabled() else str(db_path),
+        "candidates_preview": candidates_preview,
+        "context_items_count": len(context_items or []),
+    }
+    if fusion is not None and fusion.get("enabled"):
+        meta["fusion"] = fusion
+    if context_redaction is not None:
+        meta["context_redaction"] = context_redaction
+    if error:
+        meta["error"] = error
+    return meta

package/python/app/mcp_server.py

@@ -26,6 +26,7 @@ from pathlib import Path
 from app.db_paths import resolve_orchestrator_db
 from app.main import (
     build_router_and_skills,
+    format_context_items_markdown,
     init_db,
     load_all_skills,
     log_event,
@@ -36,6 +37,8 @@ from app.main import (
     Router,
 )
 from app.materialize import materialize_project_files
+from app.mcp_contract import MCP_RESPONSE_SCHEMA_VERSION, build_route_skills_meta
+from app.redaction import redaction_enabled, redact_display_path
 
 
 def _env_truthy(name: str, default: str = "1") -> bool:
@@ -97,6 +100,15 @@ class MCPServer:
         env = os.getenv("SKILLFORGE_PROJECT_ROOT", "").strip()
         return env or None
 
+    @staticmethod
+    def _include_project_rag_from_args(args: dict) -> bool:
+        v = args.get("include_project_rag")
+        if v is True:
+            return True
+        if isinstance(v, str) and v.strip().lower() in ("1", "true", "yes"):
+            return True
+        return False
+
     def _get_con(self, args: dict):
         path = resolve_orchestrator_db(self._project_root_from_args(args))
         key = str(path)
@@ -173,7 +185,7 @@ class MCPServer:
         return {
             "protocolVersion": "2024-11-05",
             "capabilities": caps,
-            "serverInfo": {"name": "skillforge", "version": "0.2.1"},
+            "serverInfo": {"name": "skillforge", "version": "0.7.0"},
         }
 
     def handle_tools_list(self, params):
@@ -183,11 +195,14 @@ class MCPServer:
                     "name": "route_skills",
                     "description": (
                         "Route the user's prompt to the most relevant skills from the catalog "
-                        "and return their full SKILL.md bodies. The client should inject the "
-                        "returned content into the LLM's context. Returns up to 7 skills. "
-                        "Pass project_root (workspace path) for per-repo SQLite in .skillforge/ "
-                        "and learning; else use env SKILLFORGE_PROJECT_ROOT or global data dir. "
-                        "Optional session_id for reroute stats; optional user_id for multi-user."
+                        "and return SKILL.md context (full body or RAG chunks per CONTEXT_MODE). "
+                        "Returns up to 7 skills. "
+                        "Pass project_root for per-repo SQLite in .skillforge/ and learning. "
+                        "Optional include_project_rag merges top chunks from `skillforge index` into context. "
+                        "On success, _meta includes schema_version ("
+                        f"{MCP_RESPONSE_SCHEMA_VERSION}), sources[] (kind skill or file), "
+                        "budget (chars_skill_bodies, chars_project_chunks), fusion (MMR when combined index+RAG), "
+                        "candidates_preview, context_items_count."
                     ),
                     "inputSchema": {
                         "type": "object",
@@ -197,6 +212,14 @@ class MCPServer:
                                 "type": "string",
                                 "description": "Repo/workspace root — stores orchestrator state in .skillforge/",
                             },
+                            "include_project_rag": {
+                                "type": "boolean",
+                                "description": (
+                                    "If true, append top chunks from the project index in the same DB "
+                                    "(see skillforge index). Requires project_root."
+                                ),
+                                "default": False,
+                            },
                             "conversation": {
                                 "type": "array",
                                 "description": "Optional recent messages for context",
@@ -317,6 +340,11 @@ class MCPServer:
                             "session_id": {"type": "string"},
                             "user_id": {"type": "string"},
                             "merge": {"type": "boolean", "default": True},
+                            "include_project_rag": {
+                                "type": "boolean",
+                                "description": "Same as route_skills: merge indexed project file chunks into context.",
+                                "default": False,
+                            },
                         },
                         "required": ["prompt", "project_root"],
                     },
@@ -349,8 +377,25 @@ class MCPServer:
         conversation = args.get("conversation", [])
         session_id = args.get("session_id") or None
         user_id = self._mcp_user_id(args)
+        pr = self._project_root_from_args(args)
+        db_path = resolve_orchestrator_db(pr)
+
         if not prompt.strip():
-            return {"content": [{"type": "text", "text": "No prompt provided."}]}
+            err_text = "No prompt provided."
+            return {
+                "content": [{"type": "text", "text": err_text}],
+                "isError": True,
+                "_meta": build_route_skills_meta(
+                    result={"candidates": []},
+                    picked_names=[],
+                    user_id=user_id,
+                    db_path=db_path,
+                    skills_map=self.skills or {},
+                    response_text=err_text,
+                    error="empty_prompt",
+                ),
+            }
+
         con = self._get_con(args)
         result = await run_route_turn(
             con,
@@ -359,11 +404,12 @@ class MCPServer:
             conversation,
             user_id=user_id,
             session_id=session_id,
+            project_root=pr,
+            include_project_rag=self._include_project_rag_from_args(args),
         )
         picked_names = result["picked_names"]
         reasoning = result["reasoning"]
-        pr = self._project_root_from_args(args)
-        db_path = resolve_orchestrator_db(pr)
+        context_items = result.get("context_items") or []
         if pr:
             try:
                 d = Path(pr).expanduser().resolve() / ".skillforge"
@@ -375,36 +421,41 @@ class MCPServer:
                     "reasoning": reasoning,
                     "route_ms": round(result["route_ms"], 1),
                     "user_id": user_id,
+                    "schema_version": MCP_RESPONSE_SCHEMA_VERSION,
+                    "context_mode": self.router.context_mode,
+                    "context_items_count": len(context_items),
+                    "project_rag_items_count": (result.get("event") or {}).get("project_rag_items_count", 0),
                 }
                 (d / "last_route.json").write_text(json.dumps(snap, indent=2), encoding="utf-8")
             except OSError:
                 pass
 
-        # Build response: a header explaining what was loaded, then the skill bodies
+        db_disp = redact_display_path(db_path) if redaction_enabled() else str(db_path)
         blocks = [
-            f"# Skillforge — routed {len(picked_names)} skill(s)",
-            f"_DB:_ `{db_path}`",
+            f"# Skillforge — routed {len(picked_names)} skill(s); context=`{self.router.context_mode}`",
+            f"_DB:_ `{db_disp}`",
             f"_Reasoning: {reasoning}_" if reasoning else "",
             "",
         ]
-        for n in picked_names:
-            s = self.skills.get(n)
-            if s:
-                blocks.append(f"---\n## Skill: {s.name}\n\n{s.body}\n")
-        if not picked_names:
+        if context_items:
+            blocks.append(format_context_items_markdown(context_items))
+        elif not picked_names:
             blocks.append("_No skills matched this prompt closely enough to load._")
+        response_text = "\n".join(b for b in blocks if b is not None)
+        meta = build_route_skills_meta(
+            result=result,
+            picked_names=picked_names,
+            user_id=user_id,
+            db_path=db_path,
+            skills_map=self.skills,
+            response_text=response_text,
+            context_items=context_items,
+            fusion=(result.get("event") or {}).get("context_fusion"),
+            context_redaction=(result.get("event") or {}).get("context_redaction"),
+        )
         return {
-            "content": [{"type": "text", "text": "\n".join(b for b in blocks if b is not None)}],
-            "_meta": {
-                "picked": picked_names,
-                "reasoning": reasoning,
-                "session_id": result["session_id"],
-                "user_id": user_id,
-                "rerouted": result["rerouted"],
-                "change_pct": round(result["change"] * 100, 1),
-                "route_ms": round(result["route_ms"], 1),
-                "orchestrator_db": str(db_path),
-            },
+            "content": [{"type": "text", "text": response_text}],
+            "_meta": meta,
         }
 
     def _tool_list_skills(self, args):
@@ -514,6 +565,7 @@ class MCPServer:
                 "conversation": conversation,
                 "session_id": session_id,
                 "user_id": user_id,
+                "include_project_rag": self._include_project_rag_from_args(args),
             }
         )
         if route.get("isError"):