tylor-mcp 1.0.0

package/server/tools/agents.py

@@ -0,0 +1,160 @@
+"""server/tools/agents.py — Tier 1 agent orchestration MCP tools."""
+from __future__ import annotations
+import uuid
+import re
+
+from mcp.shared.exceptions import McpError
+from mcp.types import ErrorData, INVALID_PARAMS
+
+from .personas import list_persona_summaries, load_persona
+from ._mcp import mcp
+
+_AGENT_ID_RE   = re.compile(r"^[a-zA-Z0-9_-]+$")
+_THREAD_ID_RE  = re.compile(r"^[a-f0-9]{32}$")  # uuid4().hex format
+
+
+def _invalid_params(message: str) -> McpError:
+    return McpError(ErrorData(code=INVALID_PARAMS, message=message))
+
+
+def _get_db():
+    from .tylor import _get_db as get_thread_db
+
+    return get_thread_db()
+
+
+def _get_memory_client():
+    from .tylor import _get_memory_client as get_thread_memory_client
+
+    return get_thread_memory_client()
+
+
+def _ensure_active_thread(db, thread_id: str) -> None:
+    meta = db.get_thread_meta(thread_id)
+    if not meta:
+        raise _invalid_params(f"Thread not found: {thread_id}")
+
+    status = meta.get("Status", meta.get("status", "active"))
+    if status != "active":
+        raise _invalid_params(f"Thread is not active: {thread_id}")
+
+
+def _available_personas_message() -> str:
+    personas = list_persona_summaries()
+    formatted = ", ".join(
+        f"{p['name']} ({', '.join(p['ecc_tool_categories'])})"
+        for p in personas
+    )
+    return f"Available personas: {formatted}"
+
+
+@mcp.tool()
+def list_personas() -> dict:
+    """
+    Return available specialist personas with role summaries and ECC categories.
+    """
+    return {"personas": list_persona_summaries()}
+
+
+@mcp.tool()
+def spawn_agent(persona: str, thread_id: str, task: str) -> dict:
+    """
+    Spawn a specialist sub-agent persona within the given thread.
+    The sub-agent is scoped to this thread — no cross-thread bleed.
+    Available personas: ceo, cto, analyst, code_agent.
+
+    Args:
+        persona: Persona identifier — one of: ceo, cto, analyst, code_agent.
+        thread_id: The thread to scope this agent to.
+        task: The work the persona should perform inside this thread.
+    """
+    if not _THREAD_ID_RE.match(thread_id):
+        raise _invalid_params(
+            f"Invalid thread_id '{thread_id}' — must be a 32-character hex UUID (e.g. uuid4().hex)"
+        )
+    definition = load_persona(persona)
+    if definition is None:
+        raise _invalid_params(
+            f"Unknown persona: {persona}. {_available_personas_message()}"
+        )
+
+    db = _get_db()
+    _ensure_active_thread(db, thread_id)
+
+    agent_id = f"agent_{uuid.uuid4().hex}"
+    state_item = db.put_agent_state(
+        thread_id=thread_id,
+        agent_id=agent_id,
+        state={
+            "Status": "active",
+            "Persona": definition.name,
+            "Task": task,
+            "ToolsLoaded": list(definition.ecc_tool_categories),
+        },
+    )
+
+    return {
+        "agent_id": agent_id,
+        "persona": definition.name,
+        "thread_id": thread_id,
+        "tools_loaded": list(definition.ecc_tool_categories),
+        "role_prompt": definition.role_prompt,
+        "task": task,
+        "state_sk": state_item["SK"],
+    }
+
+
+def persist_agent_output(
+    thread_id: str,
+    agent_id: str,
+    output: str,
+    task: str | None = None,
+    handoff_state: dict | None = None,
+) -> dict:
+    """
+    Persist completed sub-agent output and index it for scoped thread recall.
+
+    This is intentionally an orchestration helper, not a public Tier 1 MCP tool.
+    Future sub-agent execution calls this automatically when an agent completes.
+    """
+    if not _AGENT_ID_RE.match(agent_id or ""):
+        raise _invalid_params("Invalid agent_id")
+    if not output or not output.strip():
+        raise _invalid_params("Agent output must not be empty")
+
+    db = _get_db()
+    _ensure_active_thread(db, thread_id)
+
+    output_item = db.put_agent_output(
+        thread_id=thread_id,
+        agent_id=agent_id,
+        output=output,
+        task=task,
+    )
+
+    handoff_item = None
+    if handoff_state is not None:
+        handoff_item = db.put_agent_handoff(
+            thread_id=thread_id,
+            agent_id=agent_id,
+            handoff_state=handoff_state,
+        )
+
+    memory = _get_memory_client()
+    memory_id = memory.index_memory(
+        thread_id=thread_id,
+        fact=output,
+        metadata={
+            "source": "agent_output",
+            "agent_id": agent_id,
+            "agent_output_sk": output_item["SK"],
+        },
+    )
+
+    return {
+        "thread_id": thread_id,
+        "agent_id": agent_id,
+        "output_sk": output_item["SK"],
+        "handoff_sk": handoff_item["SK"] if handoff_item else None,
+        "memory_id": memory_id,
+    }

package/server/tools/ecc/__init__.py

@@ -0,0 +1 @@
+"""Lazy-loadable ECC tool categories."""

package/server/tools/ecc/data.py

@@ -0,0 +1,35 @@
+"""ECC data tools."""
+from .._mcp import mcp
+
+
+@mcp.tool()
+def dataset_manager(action: str, dataset_id: str | None = None) -> dict:
+    """Manage a dataset lifecycle action."""
+    return {
+        "tool": "dataset_manager",
+        "action": action,
+        "dataset_id": dataset_id,
+        "status": "planned",
+    }
+
+
+@mcp.tool()
+def data_clean(dataset_id: str, rules: list[str] | None = None) -> dict:
+    """Plan data cleaning for a dataset."""
+    return {
+        "tool": "data_clean",
+        "dataset_id": dataset_id,
+        "rules": rules or [],
+        "status": "planned",
+    }
+
+
+@mcp.tool()
+def data_transform(dataset_id: str, transform: str) -> dict:
+    """Plan a data transformation for a dataset."""
+    return {
+        "tool": "data_transform",
+        "dataset_id": dataset_id,
+        "transform": transform,
+        "status": "planned",
+    }

package/server/tools/ecc/diagrams.py

@@ -0,0 +1,23 @@
+"""ECC diagram tools."""
+from .._mcp import mcp
+
+
+@mcp.tool()
+def diagram_gen(kind: str, description: str) -> dict:
+    """Plan a diagram from a kind and description."""
+    return {
+        "tool": "diagram_gen",
+        "kind": kind,
+        "description": description,
+        "status": "planned",
+    }
+
+
+@mcp.tool()
+def flowchart_gen(steps: list[str]) -> dict:
+    """Plan a flowchart from ordered steps."""
+    return {
+        "tool": "flowchart_gen",
+        "steps": steps,
+        "status": "planned",
+    }

package/server/tools/ecc/pipeline.py

@@ -0,0 +1,24 @@
+"""ECC pipeline tools."""
+from .._mcp import mcp
+
+
+@mcp.tool()
+def pipeline_builder(name: str, stages: list[str]) -> dict:
+    """Plan a pipeline definition from named stages."""
+    return {
+        "tool": "pipeline_builder",
+        "name": name,
+        "stages": stages,
+        "status": "planned",
+    }
+
+
+@mcp.tool()
+def pipeline_run(pipeline_id: str, dry_run: bool = True) -> dict:
+    """Plan or request a pipeline run."""
+    return {
+        "tool": "pipeline_run",
+        "pipeline_id": pipeline_id,
+        "dry_run": dry_run,
+        "status": "planned",
+    }

package/server/tools/ecc/presentation.py

@@ -0,0 +1,24 @@
+"""ECC presentation tools."""
+from .._mcp import mcp
+
+
+@mcp.tool()
+def build_pptx(title: str, outline: list[str]) -> dict:
+    """Plan a presentation deck from a title and outline."""
+    return {
+        "tool": "build_pptx",
+        "title": title,
+        "outline": outline,
+        "status": "planned",
+    }
+
+
+@mcp.tool()
+def build_doc(title: str, sections: list[str]) -> dict:
+    """Plan a document from a title and section list."""
+    return {
+        "tool": "build_doc",
+        "title": title,
+        "sections": sections,
+        "status": "planned",
+    }

package/server/tools/ecc/web.py

@@ -0,0 +1,23 @@
+"""ECC web tools."""
+from .._mcp import mcp
+
+
+@mcp.tool()
+def web_scrape(url: str, selector: str | None = None) -> dict:
+    """Plan a structured web scrape for a URL and optional selector."""
+    return {
+        "tool": "web_scrape",
+        "url": url,
+        "selector": selector,
+        "status": "planned",
+    }
+
+
+@mcp.tool()
+def web_fetch(url: str) -> dict:
+    """Plan a direct web fetch for a URL."""
+    return {
+        "tool": "web_fetch",
+        "url": url,
+        "status": "planned",
+    }