devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/mcp/server.py

@@ -0,0 +1,1049 @@
+"""
+S7 MCP Server — DevTorch primitives exposed via JSON-RPC 2.0 / MCP protocol.
+
+Supports two transports:
+- If the `mcp` SDK is installed: uses mcp.server.Server + stdio_server
+- Fallback: raw JSON-RPC 2.0 line-by-line stdio loop
+
+Tools exposed:
+  devtorch_commit          — Commit a reasoning milestone to .GCC/
+  devtorch_sensitivity_add — Record a sensitivity signal
+  devtorch_context         — Retrieve bounded context bundle
+  devtorch_theta_read      — Read coordination vector Θ
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+# FastAPI / Starlette imports — only needed for SSE transport, but must be at
+# module level so that FastAPI can resolve string annotations (PEP 563) when
+# building the route dependency graph.
+try:
+    from fastapi import FastAPI as _FastAPI, Request as _Request, HTTPException as _HTTPException
+    from fastapi.responses import StreamingResponse as _StreamingResponse, Response as _Response
+    _FASTAPI_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    _FASTAPI_AVAILABLE = False
+    _FastAPI = None  # type: ignore[assignment,misc]
+    _Request = None  # type: ignore[assignment]
+    _HTTPException = None  # type: ignore[assignment]
+    _StreamingResponse = None  # type: ignore[assignment]
+    _Response = None  # type: ignore[assignment]
+
+# ---------------------------------------------------------------------------
+# Tool definitions (shared between MCP-SDK path and fallback path)
+# ---------------------------------------------------------------------------
+
+TOOLS: List[Dict[str, Any]] = [
+    {
+        "name": "devtorch_commit",
+        "description": "Commit a reasoning milestone to the .GCC/ store",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "message": {"type": "string", "description": "Commit message"},
+                "branch": {
+                    "type": "string",
+                    "description": "Branch name (optional)",
+                },
+                "concepts": {
+                    "type": "string",
+                    "description": "Comma-separated concept tags (optional, e.g. auth,security)",
+                },
+            },
+            "required": ["message"],
+        },
+    },
+    {
+        "name": "devtorch_sensitivity_add",
+        "description": "Record what this decision depends on (sensitivity signal)",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "concept": {"type": "string", "description": "Target concept"},
+                "signal": {
+                    "type": "string",
+                    "description": "Signal / counterfactual text",
+                },
+                "confidence": {
+                    "type": "number",
+                    "description": "Confidence in [0, 1]",
+                },
+                "disclosure": {
+                    "type": "string",
+                    "description": "Disclosure level: PUBLIC, PROTECTED (default), or PRIVATE",
+                },
+            },
+            "required": ["concept", "signal", "confidence"],
+        },
+    },
+    {
+        "name": "devtorch_context",
+        "description": "Retrieve bounded context bundle from .GCC/ (use this at session start)",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "k": {
+                    "type": "integer",
+                    "description": "Token budget (default 8000)",
+                },
+            },
+        },
+    },
+    {
+        "name": "devtorch_theta_read",
+        "description": "Read current coordination vector Θ (shared sensitivity state)",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "concepts": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Filter to specific concepts (optional)",
+                },
+            },
+        },
+    },
+    {
+        "name": "devtorch_reasoning_query",
+        "description": "Query an agent's reasoning about a specific concept (use at session start to understand prior decisions)",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "concept": {"type": "string", "description": "Concept to query (e.g. auth, schema, payments)"},
+                "agent_id": {"type": "string", "description": "Filter to a specific agent ID (optional)"},
+                "scope": {"type": "string", "description": "branch | session | org (default: branch)"},
+                "k": {"type": "integer", "description": "Token budget (default 4000)"},
+            },
+            "required": ["concept"],
+        },
+    },
+    {
+        "name": "devtorch_divergence_detect",
+        "description": "Detect reasoning divergence between agents for a concept",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "concept": {"type": "string"},
+            },
+            "required": ["concept"],
+        },
+    },
+    {
+        "name": "devtorch_consolidation_status",
+        "description": "Get consolidation record status for a concept",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "concept": {"type": "string"},
+            },
+            "required": ["concept"],
+        },
+    },
+    {
+        "name": "devtorch_hitl_respond",
+        "description": "Provide a human or agent resolution to a pending HITL consolidation",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "record_id": {"type": "string", "description": "ConsolidationRecord ID"},
+                "author": {"type": "string", "description": "Responder name or agent_id"},
+                "comment": {"type": "string", "description": "Explanation or reasoning"},
+                "decision": {"type": "string", "description": "The consolidated decision text"},
+            },
+            "required": ["record_id", "author", "decision"],
+        },
+    },
+    {
+        "name": "devtorch_reasoning_plus_config",
+        "description": "Read current Reasoning Plus settings and their source",
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+        },
+    },
+    {
+        "name": "devtorch_reasoning_plus_set",
+        "description": "Update Reasoning Plus settings for this project",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "enabled": {"type": "boolean", "description": "Enable or disable Reasoning Plus"},
+                "smart_top_n": {"type": "integer", "description": "Number of smart-context files to include"},
+                "smart_max_lines": {"type": "integer", "description": "Max lines per smart-context file"},
+                "context_k": {"type": "integer", "description": "Context token budget (used by benchmark runners)"},
+                "require_thinking": {"type": "boolean", "description": "Require <thinking> block in responses"},
+                "max_keywords": {"type": "integer", "description": "Max keywords for smart context extraction"},
+                "cache_ttl_secs": {"type": "integer", "description": "Smart context cache TTL in seconds"},
+                "learning_enabled": {"type": "boolean", "description": "Enable or disable Reasoning Plus Learning"},
+                "learning_top_n": {"type": "integer", "description": "Number of learnings to inject"},
+                "learning_max_lines": {"type": "integer", "description": "Max lines for the injected learnings block"},
+                "learning_embedding_backend": {"type": "string", "description": "Embedding backend for relevance: keyword, sentence_transformers, openai"},
+                "learning_embedding_model": {"type": "string", "description": "Model name for sentence_transformers or openai backend"},
+                "learning_extraction_strategy": {"type": "string", "description": "Learning extraction strategy: rule or llm"},
+                "learning_relevance_cache_ttl": {"type": "integer", "description": "Relevance cache TTL in seconds"},
+            },
+        },
+    },
+    {
+        "name": "devtorch_reasoning_plus_learning_query",
+        "description": "Query relevant learnings from the Reasoning Plus Learning store",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "context": {"type": "string", "description": "Current task or prompt context to match learnings against"},
+                "top_n": {"type": "integer", "description": "Maximum number of learnings to return (default: project setting)"},
+                "session_id": {"type": "string", "description": "Optional session filter"},
+                "state_hash": {"type": "string", "description": "Optional workspace state hash for freshness boost"},
+            },
+            "required": ["context"],
+        },
+    },
+    {
+        "name": "devtorch_reasoning_plus_learning_purge",
+        "description": "Purge stale or deprecated learnings from the Reasoning Plus Learning store",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "scope": {"type": "string", "description": "Scope to purge: stale, deprecated, or all"},
+                "session_id": {"type": "string", "description": "Optional session filter"},
+            },
+        },
+    },
+    {
+        "name": "devtorch_reasoning_plus_learning_feedback",
+        "description": "Apply outcome feedback to a learning (success, failure, or stale)",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "learning_id": {"type": "string", "description": "Learning ID to update"},
+                "outcome": {"type": "string", "description": "Outcome: success, failure, or stale"},
+            },
+            "required": ["learning_id", "outcome"],
+        },
+    },
+    {
+        "name": "devtorch_topics_list",
+        "description": "List all topics with captured reasoning",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "all": {"type": "boolean", "description": "Include topics with no data (default: false)"}
+            },
+        },
+    },
+    {
+        "name": "devtorch_reasoning_history",
+        "description": "Get reasoning history for a topic (expands to all concepts) or a single concept",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "topic": {"type": "string", "description": "Topic name (expands to multiple concepts)"},
+                "concept": {"type": "string", "description": "Single concept name (alternative to topic)"},
+                "max_entries": {"type": "integer", "description": "Max total entries across all concepts (default: 50)"},
+                "agent_id": {"type": "string", "description": "Filter by agent ID"}
+            },
+        },
+    },
+    {
+        "name": "devtorch_concepts_list",
+        "description": "List all concepts from all sources (I3, theta, sensitivity, learnings, commits)",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "learned_only": {"type": "boolean", "description": "Only concepts from learning interactions"}
+            },
+        },
+    },
+    {
+        "name": "devtorch_concepts_related",
+        "description": "List concepts related to a given topic",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "topic": {"type": "string"}
+            },
+            "required": ["topic"],
+        },
+    },
+    {
+        "name": "devtorch_sync_pull",
+        "description": "Pull delta from server — returns items the client doesn't have based on sync state",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "sync_state": {
+                    "type": "object",
+                    "description": "Client's current sync state (what it already has)",
+                },
+                "chunk_size": {
+                    "type": "integer",
+                    "description": "Max items per data type in response (default: 500)",
+                },
+            },
+        },
+    },
+    {
+        "name": "devtorch_sync_push",
+        "description": "Push delta to server — sends items the server doesn't have",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "bundle": {
+                    "type": "string",
+                    "description": "Base64-encoded gzip-compressed delta bundle",
+                },
+                "batch_id": {
+                    "type": "string",
+                    "description": "Batch identifier for chunking",
+                },
+                "is_last": {
+                    "type": "boolean",
+                    "description": "True if this is the final batch (default: true)",
+                },
+            },
+        },
+    },
+]
+
+# ---------------------------------------------------------------------------
+# Tool implementations
+# ---------------------------------------------------------------------------
+
+
+def _tool_devtorch_commit(repo: Any, args: dict) -> str:
+    message = args.get("message", "")
+    concepts_raw = args.get("concepts", "")
+    concepts = [c.strip() for c in concepts_raw.split(",") if c.strip()] if concepts_raw else None
+    repo.commit(message=message, concepts=concepts)
+    parts = [f"Committed to .GCC/"]
+    if concepts:
+        parts.append(f"[concepts: {', '.join(concepts)}]")
+    return " ".join(parts)
+
+
+def _tool_devtorch_sensitivity_add(repo: Any, args: dict) -> str:
+    from devtorch_core.sensitivity import SensitivityEvent
+
+    concept = args["concept"]
+    signal = args["signal"]
+    confidence = float(args["confidence"])
+    disclosure = args.get("disclosure", "PROTECTED").upper()
+    if disclosure not in ("PUBLIC", "PROTECTED", "PRIVATE"):
+        disclosure = "PROTECTED"
+
+    ev = SensitivityEvent(
+        source_node="mcp-client",
+        target_concept=concept,
+        counterfactuals=signal,
+        confidence=confidence,
+        disclosure_level=disclosure,
+        message=signal,
+    )
+    repo.add_sensitivity(ev)
+    return f"Sensitivity recorded: {concept} @ {confidence}"
+
+
+def _tool_devtorch_context(repo: Any, args: dict) -> str:
+    k = int(args.get("k", 8000))
+    bundle = repo.context_bundle(
+        k_tokens=k, policy={"sensitivity_policy": "default"}
+    )
+    # bundle is a dict; format it as a readable string
+    artifacts = bundle.get("artifacts", [])
+    if not artifacts:
+        return f"Context bundle (budget={k} tokens): no artifacts found."
+
+    lines = [f"Context bundle (budget={k} tokens, {len(artifacts)} artifacts):"]
+    for art in artifacts:
+        # Support both "name" (test mock) and "path" (real GCCRepository output)
+        name = art.get("name", art.get("path", art.get("id", "unknown")))
+        reason = art.get("reason", "")
+        # Support both "tokens" (test mock) and "approx_tokens" (real GCCRepository output)
+        tokens = art.get("tokens", art.get("approx_tokens", "?"))
+        lines.append(f"  - {name} ({tokens} tokens): {reason}")
+    return "\n".join(lines)
+
+
+def _tool_devtorch_theta_read(repo: Any, args: dict) -> str:
+    theta = repo.get_theta().get("coordination_vector", {})
+    concepts = args.get("concepts")
+    if concepts:
+        theta = {k: v for k, v in theta.items() if k in concepts}
+    return json.dumps(theta, indent=2)
+
+
+def _tool_devtorch_reasoning_query(repo: Any, args: dict) -> str:
+    from devtorch_core.reasoning import ReasoningStore
+
+    concept = args["concept"]
+    agent_id = args.get("agent_id")
+    scope = args.get("scope", "branch")
+    k = int(args.get("k", 4000))
+
+    store = ReasoningStore(repo)
+    entries = store.query(concept=concept, agent_id=agent_id, scope=scope, k_tokens=k)
+
+    if not entries:
+        return f"No reasoning entries found for concept '{concept}'."
+
+    lines = [f"Reasoning for '{concept}' ({len(entries)} entries, budget={k} tokens):"]
+    for e in entries:
+        lines.append(
+            f"\n  [{e.timestamp[:19]}] agent={e.agent_id} conf={e.confidence:.2f} [{e.disclosure_level}]"
+        )
+        lines.append(f"  Reasoning: {e.reasoning_text}")
+        if e.decision_text:
+            lines.append(f"  Decision:  {e.decision_text}")
+    return "\n".join(lines)
+
+
+def _tool_devtorch_divergence_detect(repo: Any, args: dict) -> str:
+    from devtorch_core.divergence import DivergenceDetector
+    concept = args["concept"]
+    signals = DivergenceDetector(repo).detect(concept=concept)
+    if not signals:
+        return f"No divergence detected for concept '{concept}'."
+    lines = [f"Divergence signals for '{concept}' ({len(signals)} signals):"]
+    for s in signals:
+        lines.append(f"  [{s.signal_type}/{s.severity}] {s.description}")
+    return "\n".join(lines)
+
+
+def _tool_devtorch_consolidation_status(repo: Any, args: dict) -> str:
+    from devtorch_core.consolidation import ConsolidationWorkflow
+    concept = args["concept"]
+    records = ConsolidationWorkflow(repo).list_for_concept(concept)
+    if not records:
+        return f"No consolidation records found for concept '{concept}'."
+    r = records[0]  # most recent
+    return (
+        f"Consolidation '{r.record_id[:8]}' — concept='{r.concept}' state={r.state}\n"
+        f"  Decision: {r.decision or '(pending)'}\n"
+        f"  Trace: {r.decision_trace[:200]}\n"
+        f"  Agents: {', '.join(r.agents_involved)}"
+    )
+
+
+def _tool_devtorch_hitl_respond(repo: Any, args: dict) -> str:
+    from devtorch_core.consolidation import ConsolidationWorkflow
+    record_id = args["record_id"]
+    author = args["author"]
+    comment = args.get("comment", "")
+    decision = args["decision"]
+    workflow = ConsolidationWorkflow(repo)
+    record = workflow.add_human_comment(
+        record_id=record_id,
+        author=author,
+        comment=comment or decision,
+        decision=decision,
+    )
+    return f"Recorded: consolidation '{record_id[:8]}' resolved by '{author}'. State: {record.state}."
+
+
+def _tool_devtorch_reasoning_plus_config(repo: Any, args: dict) -> str:
+    from devtorch_core.reasoning_plus import SettingsStore
+    config, source = SettingsStore(repo.gcc_dir).load()
+    return json.dumps(
+        {
+            "source": source,
+            "config": config.to_dict(),
+        },
+        indent=2,
+    )
+
+
+def _tool_devtorch_reasoning_plus_set(repo: Any, args: dict) -> str:
+    from devtorch_core.reasoning_plus import ReasoningPlusConfig, SettingsStore
+    config, _ = SettingsStore(repo.gcc_dir).load()
+    overrides = {k: v for k, v in args.items() if v is not None and k in config.to_dict()}
+    config = config.with_values(**overrides)
+    SettingsStore(repo.gcc_dir).save_project(config)
+    return f"Reasoning Plus settings updated: {json.dumps(config.to_dict(), indent=2)}"
+
+
+def _tool_devtorch_reasoning_plus_learning_query(repo: Any, args: dict) -> str:
+    from devtorch_core.reasoning_plus import ReasoningPlusConfig, ReasoningPlusLearning, SettingsStore
+    config, _ = SettingsStore(repo.gcc_dir).load()
+    drpl = ReasoningPlusLearning(gcc_dir=repo.gcc_dir, repo_path=repo.root, config=config)
+    context = args["context"]
+    top_n = args.get("top_n")
+    state_hash = args.get("state_hash")
+    learnings = drpl.get_relevant_learnings(context, top_n=top_n, state_hash=state_hash)
+    session_id = args.get("session_id")
+    if session_id:
+        learnings = [l for l in learnings if session_id in l.meta.get("session_id", "") or not session_id]
+    result = [
+        {
+            "id": l.id,
+            "type": l.type,
+            "content": l.short_form(max_chars=300),
+            "confidence": l.confidence,
+            "validity": l.validity,
+            "state_hash": l.state_hash,
+            "trigger_concepts": l.trigger_concepts,
+        }
+        for l in learnings
+    ]
+    return json.dumps({"count": len(result), "learnings": result}, indent=2)
+
+
+def _tool_devtorch_reasoning_plus_learning_purge(repo: Any, args: dict) -> str:
+    from devtorch_core.reasoning_plus import ReasoningPlusConfig, ReasoningPlusLearning, SettingsStore
+    config, _ = SettingsStore(repo.gcc_dir).load()
+    drpl = ReasoningPlusLearning(gcc_dir=repo.gcc_dir, repo_path=repo.root, config=config)
+    scope = args.get("scope", "stale").lower()
+    session_id = args.get("session_id")
+    if scope not in ("stale", "deprecated", "all"):
+        raise ValueError(f"Invalid purge scope: {scope}")
+    target_validity = None if scope == "all" else scope
+    learnings = drpl._store.list(validity=target_validity)
+    if session_id:
+        learnings = [l for l in learnings if any(
+            drpl._recorder.get(cid) and drpl._recorder.get(cid).session_id == session_id
+            for cid in l.source_reasoning_ids
+        )]
+    count = 0
+    for learning in learnings:
+        drpl._store.invalidate(learning.id, reason="purged")
+        count += 1
+    return f"Purged {count} learning(s) (scope={scope})."
+
+
+def _tool_devtorch_reasoning_plus_learning_feedback(repo: Any, args: dict) -> str:
+    from devtorch_core.reasoning_plus import ReasoningPlusConfig, ReasoningPlusLearning, SettingsStore
+    config, _ = SettingsStore(repo.gcc_dir).load()
+    drpl = ReasoningPlusLearning(gcc_dir=repo.gcc_dir, repo_path=repo.root, config=config)
+    learning_id = args["learning_id"]
+    outcome = args["outcome"]
+    updated = drpl.apply_feedback(learning_id, outcome)
+    if updated is None:
+        return f"Learning {learning_id} not found."
+    return json.dumps(
+        {
+            "id": updated.id,
+            "validity": updated.validity,
+            "confidence": updated.confidence,
+        },
+        indent=2,
+    )
+
+
+def _tool_devtorch_topics_list(repo: Any, args: dict) -> str:
+    from devtorch_core.topics import TopicStore
+    show_all = args.get("all", False)
+    store = TopicStore(repo.gcc_dir)
+    topics = store.list_topics(with_data_only=not show_all)
+    if not topics:
+        return "No topics found."
+    lines = []
+    for t in topics:
+        tag = f"  [{t['source']}]" if t["source"] != "default" else ""
+        lines.append(f"  {t['name']:<20} ({len(t['concepts'])} concepts: {', '.join(t['concepts'])}){tag}")
+    header = "Topics" + (" (full taxonomy)" if show_all else " with captured reasoning") + ":\n"
+    return header + "\n".join(lines)
+
+
+def _tool_devtorch_reasoning_history(repo: Any, args: dict) -> str:
+    from devtorch_core.reasoning import ReasoningStore
+    from devtorch_core.topics import TopicStore
+    topic = args.get("topic")
+    concept = args.get("concept")
+    max_entries = int(args.get("max_entries", 50))
+    agent_id = args.get("agent_id")
+
+    if not topic and not concept:
+        return "Provide either 'topic' or 'concept'."
+
+    store = ReasoningStore(repo)
+
+    if concept:
+        entries = store.query(concept=concept, agent_id=agent_id, k_tokens=4000)
+        return _format_reasoning_entries(concept, entries, max_entries)
+
+    if topic:
+        topic_store = TopicStore(repo.gcc_dir)
+        concepts = topic_store.get_concepts(topic)
+        if not concepts:
+            return f"Topic '{topic}' not found."
+        all_lines = [f"Reasoning history for topic '{topic}' ({len(concepts)} concepts):\n"]
+        total = 0
+        for c in concepts:
+            entries = store.query(concept=c, agent_id=agent_id, k_tokens=4000)
+            if entries:
+                all_lines.append(_format_reasoning_entries(c, entries, max_entries - total))
+                total += len(entries)
+                if total >= max_entries:
+                    break
+        all_lines.append(f"\nTotal: {total} reasoning entries across {len(concepts)} concepts (capped at {max_entries}).")
+        return "\n".join(all_lines)
+
+    return "No results."
+
+
+def _format_reasoning_entries(label: str, entries: list, max_entries: int) -> str:
+    if not entries:
+        return f"\n═══ {label} (0 entries) ═══\n  No reasoning found."
+    shown = entries[:max_entries] if max_entries > 0 else entries
+    lines = [f"\n═══ {label} ({len(entries)} entries, showing {len(shown)}) ═══"]
+    for e in shown:
+        lines.append(f"  [{e.timestamp[:19]}] agent={e.agent_id} conf={e.confidence:.2f} [{e.disclosure_level}]")
+        lines.append(f"  Reasoning: {e.reasoning_text}")
+        if e.decision_text:
+            lines.append(f"  Decision:  {e.decision_text}")
+    return "\n".join(lines)
+
+
+def _tool_devtorch_concepts_list(repo: Any, args: dict) -> str:
+    from devtorch_core.concept_catalog import ConceptCatalog
+    learned_only = args.get("learned_only", False)
+    catalog = ConceptCatalog(repo.gcc_dir)
+    if learned_only:
+        learned = catalog.enumerate_learned()
+        if not learned:
+            return "No concepts with learning data found."
+        lines = ["Concepts learned from interactions:\n"]
+        for cname, stats in sorted(learned.items()):
+            lines.append(
+                f"  {cname:<16} {stats['learning_count']} learnings, "
+                f"{stats['active']} active, "
+                f"{stats['success_rate']:.0%} success, "
+                f"conf={stats['avg_confidence']:.2f}"
+            )
+        return "\n".join(lines)
+    else:
+        all_concepts = catalog.enumerate_all()
+        if not all_concepts:
+            return "No concepts found."
+        lines = [f"All concepts ({len(all_concepts)} from multiple sources):\n"]
+        for cname, sources in all_concepts.items():
+            lines.append(f"  {cname:<16} {', '.join(sources)}")
+        return "\n".join(lines)
+
+
+def _tool_devtorch_concepts_related(repo: Any, args: dict) -> str:
+    from devtorch_core.concept_catalog import ConceptCatalog
+    topic = args["topic"]
+    catalog = ConceptCatalog(repo.gcc_dir)
+    result = catalog.concepts_for_topic(topic, hide_empty=True)
+    concepts = result.get("concepts", [])
+    taxonomy_only = result.get("taxonomy_only", [])
+    if not concepts and not taxonomy_only:
+        return f"Topic '{topic}' not found or has no concepts."
+    lines = [f"Concepts related to topic '{topic}':\n"]
+    for c in concepts:
+        parts = [f"  {c['name']:<16}"]
+        parts.append(f"sources: {', '.join(c['sources'])}")
+        if "learning_count" in c:
+            parts.append(f"{c['learning_count']} learnings, {c['success_rate']:.0%} success")
+        lines.append(" — ".join(parts))
+    if taxonomy_only:
+        lines.append(f"\n  Also in taxonomy (no data): {', '.join(taxonomy_only)}")
+    lines.append(f"\n{len(concepts)} concept(s) with data. Use 'devtorch reasoning history --topic {topic}' for full history.")
+    return "\n".join(lines)
+
+
+def _tool_devtorch_sync_pull(repo: Any, args: dict) -> str:
+    import json as _json
+    from devtorch_core.cloud.sync_bundle import build_remote_delta, build_server_state, compress
+    client_state = args.get("sync_state", {})
+    delta = build_remote_delta(repo.gcc_dir, client_state)
+    server_state = build_server_state(repo.gcc_dir)
+    compressed = compress({
+        "delta": delta,
+        "server_state": server_state,
+        "counts": {k: len(v) if isinstance(v, list) else len(v.get("coordination_vector", {})) if isinstance(v, dict) else 0 for k, v in delta.items()},
+    })
+    return _json.dumps({"bundle": compressed, "server_state": server_state})
+
+
+def _tool_devtorch_sync_push(repo: Any, args: dict) -> str:
+    import json as _json
+    from devtorch_core.cloud.sync_bundle import decompress, merge_push, build_server_state
+    from devtorch_core.cloud.sync_conflicts import ConflictLog
+    encoded = args.get("bundle", "")
+    if not encoded:
+        return _json.dumps({"error": "No bundle provided"})
+    delta = decompress(encoded)
+    conflict_log = ConflictLog(repo.gcc_dir)
+    result = merge_push(repo.gcc_dir, delta, conflict_log)
+    server_state = build_server_state(repo.gcc_dir)
+    return _json.dumps({
+        "counts": result["counts"],
+        "conflicts": result["conflicts"],
+        "server_state": server_state,
+    })
+
+
+def _dispatch_tool(repo: Any, name: str, args: dict) -> str:
+    if name == "devtorch_commit":
+        return _tool_devtorch_commit(repo, args)
+    elif name == "devtorch_sensitivity_add":
+        return _tool_devtorch_sensitivity_add(repo, args)
+    elif name == "devtorch_context":
+        return _tool_devtorch_context(repo, args)
+    elif name == "devtorch_theta_read":
+        return _tool_devtorch_theta_read(repo, args)
+    elif name == "devtorch_reasoning_query":
+        return _tool_devtorch_reasoning_query(repo, args)
+    elif name == "devtorch_divergence_detect":
+        return _tool_devtorch_divergence_detect(repo, args)
+    elif name == "devtorch_consolidation_status":
+        return _tool_devtorch_consolidation_status(repo, args)
+    elif name == "devtorch_hitl_respond":
+        return _tool_devtorch_hitl_respond(repo, args)
+    elif name == "devtorch_reasoning_plus_config":
+        return _tool_devtorch_reasoning_plus_config(repo, args)
+    elif name == "devtorch_reasoning_plus_set":
+        return _tool_devtorch_reasoning_plus_set(repo, args)
+    elif name == "devtorch_reasoning_plus_learning_query":
+        return _tool_devtorch_reasoning_plus_learning_query(repo, args)
+    elif name == "devtorch_reasoning_plus_learning_purge":
+        return _tool_devtorch_reasoning_plus_learning_purge(repo, args)
+    elif name == "devtorch_reasoning_plus_learning_feedback":
+        return _tool_devtorch_reasoning_plus_learning_feedback(repo, args)
+    elif name == "devtorch_topics_list":
+        return _tool_devtorch_topics_list(repo, args)
+    elif name == "devtorch_reasoning_history":
+        return _tool_devtorch_reasoning_history(repo, args)
+    elif name == "devtorch_concepts_list":
+        return _tool_devtorch_concepts_list(repo, args)
+    elif name == "devtorch_concepts_related":
+        return _tool_devtorch_concepts_related(repo, args)
+    elif name == "devtorch_sync_pull":
+        return _tool_devtorch_sync_pull(repo, args)
+    elif name == "devtorch_sync_push":
+        return _tool_devtorch_sync_push(repo, args)
+    else:
+        raise ValueError(f"Unknown tool: {name}")
+
+
+# ---------------------------------------------------------------------------
+# MCP SDK path
+# ---------------------------------------------------------------------------
+
+
+def _run_with_sdk(repo: Any) -> None:
+    """Run using the official mcp Python SDK."""
+    import asyncio
+    from mcp.server import Server
+    from mcp.server.stdio import stdio_server
+    import mcp.types as types
+
+    server = Server("devtorch")
+
+    @server.list_tools()  # type: ignore[misc]
+    async def list_tools() -> List[types.Tool]:
+        result = []
+        for t in TOOLS:
+            result.append(
+                types.Tool(
+                    name=t["name"],
+                    description=t["description"],
+                    inputSchema=t["inputSchema"],
+                )
+            )
+        return result
+
+    @server.call_tool()  # type: ignore[misc]
+    async def call_tool(
+        name: str, arguments: dict
+    ) -> List[types.TextContent]:
+        try:
+            text = _dispatch_tool(repo, name, arguments or {})
+        except Exception as exc:
+            text = f"Error: {exc}"
+        return [types.TextContent(type="text", text=text)]
+
+    async def _run() -> None:
+        async with stdio_server() as (read_stream, write_stream):
+            await server.run(
+                read_stream,
+                write_stream,
+                server.create_initialization_options(),
+            )
+
+    asyncio.run(_run())
+
+
+# ---------------------------------------------------------------------------
+# Minimal JSON-RPC 2.0 fallback
+# ---------------------------------------------------------------------------
+
+_JSONRPC_VERSION = "2.0"
+
+
+def _make_response(id: Any, result: Any) -> dict:
+    return {"jsonrpc": _JSONRPC_VERSION, "id": id, "result": result}
+
+
+def _make_error(id: Any, code: int, message: str) -> dict:
+    return {
+        "jsonrpc": _JSONRPC_VERSION,
+        "id": id,
+        "error": {"code": code, "message": message},
+    }
+
+
+def _handle_request(repo: Any, req: dict) -> Optional[dict]:
+    """Dispatch a single JSON-RPC request and return the response dict (or None for notifications)."""
+    req_id = req.get("id")
+    method = req.get("method", "")
+    params = req.get("params") or {}
+
+    # Notifications (no id) — process but no response
+    is_notification = "id" not in req
+
+    if method == "initialize":
+        result = {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "devtorch", "version": "0.7.0"},
+        }
+        if is_notification:
+            return None
+        return _make_response(req_id, result)
+
+    elif method == "notifications/initialized":
+        return None  # no response for notifications
+
+    elif method == "tools/list":
+        result = {"tools": TOOLS}
+        if is_notification:
+            return None
+        return _make_response(req_id, result)
+
+    elif method == "tools/call":
+        name = params.get("name", "")
+        arguments = params.get("arguments") or {}
+        try:
+            text = _dispatch_tool(repo, name, arguments)
+            result = {
+                "content": [{"type": "text", "text": text}],
+                "isError": False,
+            }
+        except Exception as exc:
+            result = {
+                "content": [{"type": "text", "text": f"Error: {exc}"}],
+                "isError": True,
+            }
+        if is_notification:
+            return None
+        return _make_response(req_id, result)
+
+    elif method == "ping":
+        if is_notification:
+            return None
+        return _make_response(req_id, {})
+
+    else:
+        if is_notification:
+            return None
+        return _make_error(req_id, -32601, f"Method not found: {method}")
+
+
+def _run_raw_stdio(repo: Any) -> None:
+    """Minimal JSON-RPC 2.0 stdio loop (fallback when mcp SDK not installed)."""
+    for raw_line in sys.stdin:
+        raw_line = raw_line.strip()
+        if not raw_line:
+            continue
+        try:
+            req = json.loads(raw_line)
+        except json.JSONDecodeError as exc:
+            resp = _make_error(None, -32700, f"Parse error: {exc}")
+            sys.stdout.write(json.dumps(resp) + "\n")
+            sys.stdout.flush()
+            continue
+
+        try:
+            resp = _handle_request(repo, req)
+        except Exception as exc:
+            resp = _make_error(req.get("id"), -32603, f"Internal error: {exc}")
+
+        if resp is not None:
+            sys.stdout.write(json.dumps(resp) + "\n")
+            sys.stdout.flush()
+
+
+# ---------------------------------------------------------------------------
+# Server entry points
+# ---------------------------------------------------------------------------
+
+
+def run_server(repo: Any) -> None:
+    """Run the MCP server using the best available transport."""
+    try:
+        import mcp  # noqa: F401
+        _run_with_sdk(repo)
+    except ImportError:
+        _run_raw_stdio(repo)
+
+
+def find_gcc_repo() -> Optional[Any]:
+    """
+    Find an initialised .GCC/ repository.
+
+    Search order:
+    1. DEVTORCH_GCC_PATH env var — explicit project root (used by IDE MCP configs)
+    2. Walk upward from cwd
+    """
+    import os
+    from devtorch_core import GCCRepository
+
+    explicit = os.environ.get("DEVTORCH_GCC_PATH", "").strip()
+    if explicit:
+        r = GCCRepository.at(Path(explicit))
+        if r.is_initialized():
+            return r
+
+    for parent in [Path.cwd()] + list(Path.cwd().parents):
+        r = GCCRepository.at(parent)
+        if r.is_initialized():
+            return r
+    return None
+
+
+def main() -> None:
+    """Entry point: devtorch mcp-server"""
+    gcc = find_gcc_repo()
+    if gcc is None:
+        print(
+            "error: no .GCC/ found in current directory or parents. "
+            "Set DEVTORCH_GCC_PATH=/path/to/project to point to your project root.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    run_server(gcc)
+
+
+# ---------------------------------------------------------------------------
+# SSE transport (cloud MCP server)
+# ---------------------------------------------------------------------------
+
+import asyncio as _asyncio
+import uuid as _uuid_mod
+import json as _json_mod
+from typing import Callable as _Callable
+
+# Global session registry: session_id → (asyncio.Queue, GCCRepository)
+_session_queues: dict[str, tuple[_asyncio.Queue, Any]] = {}
+
+
+def build_sse_app(
+    repo_factory: _Callable[[str, str], Any],
+    auth_backend: Any = None,
+) -> Any:
+    """Build the FastAPI app for the cloud SSE MCP server."""
+    # Use module-level _FastAPI / _Request etc. so FastAPI can resolve the
+    # string annotations produced by `from __future__ import annotations`.
+    app = _FastAPI(title="DevTorch Cloud MCP Server")
+
+    if auth_backend is not None:
+        from devtorch_core.mcp.auth import APIKeyMiddleware, OAuthMiddleware
+        import os
+        jwks_urls = [u for u in os.environ.get("DEVTORCH_JWKS_URLS", "").split(",") if u]
+        if jwks_urls:
+            app.add_middleware(OAuthMiddleware, jwks_urls=jwks_urls)
+        app.add_middleware(APIKeyMiddleware, backend=auth_backend)
+
+    @app.get("/{org_id}/{repo_id}/sse")
+    async def sse_endpoint(org_id: str, repo_id: str, request: _Request):
+        session_id = str(_uuid_mod.uuid4())
+        queue: _asyncio.Queue = _asyncio.Queue()
+        repo = repo_factory(org_id, repo_id)
+        _session_queues[session_id] = (queue, repo)
+
+        base_url = str(request.base_url).rstrip("/")
+        messages_url = f"{base_url}/{org_id}/{repo_id}/messages?sessionId={session_id}"
+
+        async def event_stream():
+            try:
+                yield f"event: endpoint\ndata: {messages_url}\n\n"
+                while True:
+                    try:
+                        item = await _asyncio.wait_for(queue.get(), timeout=30)
+                        yield f"event: message\ndata: {_json_mod.dumps(item)}\n\n"
+                    except _asyncio.TimeoutError:
+                        yield ": keepalive\n\n"
+            finally:
+                _session_queues.pop(session_id, None)
+
+        return _StreamingResponse(
+            event_stream(),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+        )
+
+    @app.post("/{org_id}/{repo_id}/messages")
+    async def messages_endpoint(org_id: str, repo_id: str, sessionId: str, request: _Request):
+        entry = _session_queues.get(sessionId)
+        if entry is None:
+            raise _HTTPException(status_code=404, detail="Session not found")
+
+        queue, repo = entry
+        body = await request.json()
+
+        if not isinstance(body, dict):
+            raise _HTTPException(status_code=400, detail="Request body must be a JSON object")
+
+        try:
+            response = _handle_request(repo, body)
+        except Exception as exc:
+            response = _make_error(body.get("id"), -32603, str(exc))
+
+        if response is not None:
+            await queue.put(response)
+
+        return _Response(status_code=202)
+
+    @app.get("/health")
+    async def health():
+        return {"status": "ok"}
+
+    @app.get("/readyz")
+    async def readyz():
+        return {"status": "ready"}
+
+    @app.post("/github/webhook")
+    async def github_webhook(request: _Request) -> _Response:
+        import os
+        secret = os.environ.get("GITHUB_APP_WEBHOOK_SECRET", "").encode()
+        if not secret:
+            return _Response(status_code=501, content=b"GitHub App not configured")
+
+        body = await request.body()
+        signature = request.headers.get("X-Hub-Signature-256", "")
+        event_type = request.headers.get("X-GitHub-Event", "")
+
+        if auth_backend is None:
+            return _Response(status_code=503, content=b"No auth backend configured")
+
+        from devtorch_core.github.app import GitHubAppHandler
+        handler = GitHubAppHandler(backend=auth_backend, webhook_secret=secret)
+        result = handler.handle_webhook(body=body, signature=signature, event_type=event_type)
+
+        if result["status"] == "forbidden":
+            return _Response(status_code=403, content=b"Forbidden")
+        return _Response(
+            status_code=200,
+            content=json.dumps(result).encode(),
+            media_type="application/json",
+        )
+
+    return app
+
+
+def _run_with_sse(
+    repo_factory: _Callable[[str, str], Any],
+    auth_backend: Any = None,
+    host: str = "0.0.0.0",
+    port: int = 8080,
+) -> None:
+    import uvicorn
+    app = build_sse_app(repo_factory=repo_factory, auth_backend=auth_backend)
+    uvicorn.run(app, host=host, port=port)