hoja-cli 0.21.4__py3-none-any.whl

hoja/mcp/prompts.py

@@ -0,0 +1,298 @@
+"""MCP prompt templates.
+
+Each prompt returns a multi-line markdown string. The MCP client renders this
+as a user message that walks the agent through running `hoja` commands in
+a specific order. Every prompt:
+
+  1. Lists the exact shell commands to execute (in order).
+  2. Says what to look for in each response.
+  3. Includes the standard behavioral reminder at the end.
+
+The prompts NEVER perform mutations themselves. They tell the agent which
+`hoja` commands to call via the Bash tool.
+"""
+from __future__ import annotations
+
+REMINDER = (
+    "REMINDER: run each command above via the Bash tool. Do not write Python "
+    "wrappers around Linear's GraphQL API — `hoja` is the supported "
+    "interface. Use `--output json` when piping or programmatically reading."
+)
+
+
+def triage(team_key: str) -> str:
+    """Walk the agent through triaging unassigned issues for a team."""
+    return f"""# Triage workflow for team `{team_key}`
+
+You are about to triage the unassigned backlog for team **{team_key}**.
+
+## Step 1 — Scope the queue
+
+Run:
+
+```bash
+hoja issue list --team {team_key} --no-assignee --state Todo -n 20
+```
+
+Read the list. Identify the top 3–5 issues that look highest-priority based on
+title + label.
+
+## Step 2 — Inspect each candidate
+
+For each candidate ID:
+
+```bash
+hoja issue get <ID>
+```
+
+Skim the description and recent comments. Decide:
+
+- Does it have enough context? If not, comment asking the reporter.
+- Is the priority field obviously wrong? Note the correction.
+- Is the right label set?
+
+## Step 3 — Act
+
+For each issue you've decided to take action on:
+
+```bash
+hoja issue assign <ID> <USER_NAME>   # or 'me'
+hoja issue update <ID> --priority <N> --label "<labels>"
+hoja issue state <ID> "<NEXT_STATE>"   # e.g. "In Progress"
+```
+
+## Step 4 — Document
+
+If the triage decision needs a paper trail (e.g. reassigning across teams),
+post a comment:
+
+```bash
+hoja comment add <ID> --body "Triaged: assigned to <name>, priority <N> because <reason>"
+```
+
+{REMINDER}
+"""
+
+
+def daily_standup() -> str:
+    """Render a standup-shaped report of viewer's current work."""
+    return f"""# Daily standup workflow
+
+## Step 1 — What I shipped yesterday
+
+```bash
+hoja -o md issue list --assignee me --state Done \\
+    --updated-after $(date -d "1 day ago" +%Y-%m-%d) -n 20
+```
+
+## Step 2 — What I'm working on today
+
+```bash
+hoja -o md issue list --assignee me --state "In Progress" -n 20
+hoja -o md issue list --assignee me --state "In Review" -n 20
+```
+
+## Step 3 — Blockers
+
+```bash
+hoja -o md issue list --assignee me --label blocked -n 10
+```
+
+## Step 4 — Compose the standup
+
+Combine the three sections above into:
+
+```
+## Yesterday
+- <ENG-XX>: title
+- ...
+
+## Today
+- <ENG-YY>: title
+- ...
+
+## Blockers
+- <ENG-ZZ>: title — reason
+```
+
+{REMINDER}
+"""
+
+
+def create_from_error(error_text: str, team_key: str, priority: int = 3) -> str:
+    """Templated issue creation from an error message / stack trace."""
+    # Extract a plausible title — first line of the error, capped at ~80 chars
+    first_line = (error_text or "").strip().splitlines()[:1]
+    title_hint = (first_line[0][:80] if first_line else "Unhandled error").strip()
+    return f"""# Create issue from error workflow
+
+The user has provided an error trace and asked you to file an issue.
+
+## Step 1 — Search for duplicates FIRST
+
+```bash
+hoja issue search "{title_hint}" -n 5
+```
+
+If a matching issue exists, do not create a new one — comment on the existing
+issue instead:
+
+```bash
+hoja comment add <EXISTING_ID> --body "<<<DELIM
+{error_text}
+DELIM"
+```
+
+## Step 2 — If no duplicate, create
+
+```bash
+hoja issue create \\
+    --team {team_key} \\
+    --title "{title_hint}" \\
+    --description "<<<DELIM
+{error_text}
+DELIM" \\
+    --priority {priority} \\
+    --label "bug"
+```
+
+## Step 3 — Capture the new identifier
+
+The create response includes the new issue's identifier (e.g. `{team_key}-NN`).
+Surface it to the user along with `hoja issue url <ID>` for a clickable link.
+
+{REMINDER}
+"""
+
+
+def hand_off(issue_id: str, to_user: str, note: str = "") -> str:
+    """Three-command issue hand-off pattern."""
+    note_line = note or "context: see related PR / discussion / commit"
+    return f"""# Hand-off workflow for {issue_id} → {to_user}
+
+A clean hand-off is three commands. Run them in order:
+
+## Step 1 — Reassign
+
+```bash
+hoja issue assign {issue_id} "{to_user}"
+```
+
+## Step 2 — Move to a review/blocked state
+
+```bash
+hoja issue state {issue_id} "In Review"
+```
+
+(Substitute the right state name. Use `hoja team states <TEAM_KEY>` if you
+need to confirm available states for this team.)
+
+## Step 3 — Document the hand-off
+
+```bash
+hoja comment add {issue_id} --body "Handing off to {to_user} — {note_line}"
+```
+
+**Behavioral rule:** never reassign without a comment explaining why and what
+the receiver needs to know. A bare reassignment creates ambiguity downstream.
+
+{REMINDER}
+"""
+
+
+def cycle_review(team_key: str) -> str:
+    """Render a current-cycle review for a team."""
+    return f"""# Cycle review workflow for team `{team_key}`
+
+## Step 1 — Confirm there is an active cycle
+
+```bash
+hoja cycle current {team_key}
+```
+
+If the response indicates no active cycle, stop and tell the user — there is
+nothing to review.
+
+## Step 2 — Inventory the cycle by state
+
+```bash
+hoja -o json issue list --cycle current --team {team_key} \\
+    | jq 'group_by(.state.name) | map({{state: .[0].state.name, count: length, issues: map(.identifier)}})'
+```
+
+## Step 3 — Flag blockers
+
+```bash
+hoja issue list --cycle current --team {team_key} --label blocked
+```
+
+## Step 4 — Flag stale issues (no update in 5+ days)
+
+```bash
+hoja issue list --cycle current --team {team_key} \\
+    --updated-before $(date -d "5 days ago" +%Y-%m-%d)
+```
+
+## Step 5 — Report
+
+Combine the above into a structured summary:
+
+- **Done**: N issues
+- **In Progress**: N issues
+- **Todo (not started)**: N issues — risk if cycle ends soon
+- **Blockers**: list with reasons
+- **Stale**: list with last-update dates
+
+{REMINDER}
+"""
+
+
+def issue_investigate(issue_id: str) -> str:
+    """Deep dive on a single issue."""
+    return f"""# Investigate {issue_id} — full context dump
+
+## Step 1 — Read the issue
+
+```bash
+hoja -o json issue get {issue_id}
+```
+
+Capture: title, description, state, priority, assignee, labels, project, cycle.
+
+## Step 2 — Read every comment
+
+```bash
+hoja comment list {issue_id} -n 100
+```
+
+## Step 3 — Find related issues (same labels)
+
+```bash
+LABEL=$(hoja -o json issue get {issue_id} | jq -r '.labels[0].name // empty')
+[ -n "$LABEL" ] && hoja issue list --label "$LABEL" -n 10
+```
+
+## Step 4 — Find related issues (same project / cycle)
+
+```bash
+PROJECT=$(hoja -o json issue get {issue_id} | jq -r '.project.id // empty')
+[ -n "$PROJECT" ] && hoja issue list --project "$PROJECT" -n 10
+
+CYCLE=$(hoja -o json issue get {issue_id} | jq -r '.cycle.id // empty')
+[ -n "$CYCLE" ] && hoja -o json issue list --cycle "$CYCLE" | jq '[.[] | .identifier]'
+```
+
+## Step 5 — Suggest next action
+
+Based on state + labels + comments, suggest one of:
+- comment with a clarifying question
+- assign (with `hoja issue assign`)
+- move state (with `hoja issue state`)
+- close as duplicate (set state to `Canceled` and link via comment)
+- prioritize (with `hoja issue prio`)
+
+Do **not** mutate the issue yet — propose the action and wait for the user's
+go-ahead.
+
+{REMINDER}
+"""

hoja/mcp/resources.py

@@ -0,0 +1,213 @@
+"""Read-only Linear resources exposed via MCP.
+
+Each resource handler:
+  1. Resolves auth (LinearClient via env / config).
+  2. Issues a GraphQL query.
+  3. Validates response into a Pydantic model.
+  4. Returns JSON text (string).
+
+If auth is missing, the handler raises `RuntimeError` with a friendly message;
+the FastMCP runtime maps that to a JSON-RPC error so the server keeps running.
+
+All resources are **read-only**. Mutations live in the `hoja` CLI — the
+agent is expected to call those via the Bash tool. The `reminder` field on
+the tool response and the prompt bodies reinforce this rule.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from hoja.client import LinearClient
+from hoja.config import load_config, resolve_account, resolve_token
+from hoja.errors import AuthError, HojaError
+from hoja.graphql import queries
+from hoja.models.cycle import Cycle
+from hoja.models.issue import Issue
+from hoja.models.project import Project
+from hoja.models.team import Team
+from hoja.models.user import User
+from hoja.models.workflow import WorkflowState
+
+
+# ---------------------------------------------------------------------------
+# Auth helper
+# ---------------------------------------------------------------------------
+def _client() -> LinearClient:
+    """Build a LinearClient using the same resolution rules as the CLI.
+
+    Order: $HOJA_TOKEN env var (deprecated alias $LINEAR_TOKEN) > config.toml.
+    The `--token` CLI flag is not applicable here (the MCP server has no CLI
+    args for the token).
+    """
+    cfg = load_config()
+    try:
+        _account_name, account_cfg = resolve_account(None, cfg)
+        token = resolve_token(None, account_cfg)
+    except AuthError as e:
+        raise RuntimeError(
+            "hoja-mcp could not resolve an API token. "
+            "Set $HOJA_TOKEN, or run `hoja init` and put your token in "
+            "~/.config/hoja/config.toml. "
+            f"Underlying error: {e}"
+        ) from e
+    return LinearClient(token)
+
+
+def _to_json(model: Any) -> str:
+    """Serialize a Pydantic model (or list of them) to indented JSON."""
+    if isinstance(model, list):
+        return json.dumps(
+            [m.model_dump(mode="json", exclude_none=True) for m in model],
+            indent=2,
+            ensure_ascii=False,
+        )
+    if hasattr(model, "model_dump"):
+        return model.model_dump_json(indent=2, exclude_none=True)
+    return json.dumps(model, indent=2, ensure_ascii=False, default=str)
+
+
+# ---------------------------------------------------------------------------
+# Resource handlers
+# ---------------------------------------------------------------------------
+async def viewer() -> str:
+    """hoja://me — currently-authenticated user."""
+    async with _client() as c:
+        user = await c.execute_as(
+            User, queries.VIEWER, path=["viewer"], operation="Viewer"
+        )
+    return _to_json(user)
+
+
+async def issue(id: str) -> str:
+    """hoja://issue/{id} — full Issue including comments, labels, subscribers."""
+    async with _client() as c:
+        issue_model = await c.execute_as(
+            Issue,
+            queries.ISSUE_BY_IDENTIFIER,
+            {"id": id},
+            path=["issue"],
+            operation="IssueByIdentifier",
+        )
+    return _to_json(issue_model)
+
+
+async def team(key: str) -> str:
+    """hoja://team/{key} — team + states + members rolled into one payload."""
+    async with _client() as c:
+        # Resolve team id from key
+        team_data = await c.execute(
+            queries.TEAM_BY_KEY, {"key": key}, operation="TeamByKey"
+        )
+        nodes = (team_data.get("teams") or {}).get("nodes") or []
+        if not nodes:
+            raise RuntimeError(f"No team found with key {key!r}")
+        team_model = Team.model_validate(nodes[0])
+
+        # States
+        states_raw = await c.execute(
+            queries.TEAM_STATES, {"teamId": team_model.id}, operation="TeamStates"
+        )
+        state_nodes = (
+            (states_raw.get("team") or {}).get("states") or {}
+        ).get("nodes") or []
+        states = [WorkflowState.model_validate(s) for s in state_nodes]
+
+        # Members
+        members_raw = await c.execute(
+            queries.TEAM_MEMBERS, {"teamId": team_model.id}, operation="TeamMembers"
+        )
+        member_nodes = (
+            (members_raw.get("team") or {}).get("members") or {}
+        ).get("nodes") or []
+        members = [User.model_validate(m) for m in member_nodes]
+
+    payload = {
+        "team": team_model.model_dump(mode="json", exclude_none=True),
+        "states": [s.model_dump(mode="json", exclude_none=True) for s in states],
+        "members": [m.model_dump(mode="json", exclude_none=True) for m in members],
+    }
+    return json.dumps(payload, indent=2, ensure_ascii=False, default=str)
+
+
+async def project(id_or_slug: str) -> str:
+    """hoja://project/{id_or_slug} — Project with lead + members."""
+    async with _client() as c:
+        proj = await c.execute_as(
+            Project,
+            queries.PROJECT_BY_ID,
+            {"id": id_or_slug},
+            path=["project"],
+            operation="Project",
+        )
+    return _to_json(proj)
+
+
+async def cycle_current(team_key: str) -> str:
+    """hoja://cycle/current/{team_key} — active cycle or {"active_cycle": null}."""
+    async with _client() as c:
+        # Resolve team id from key
+        team_data = await c.execute(
+            queries.TEAM_BY_KEY, {"key": team_key}, operation="TeamByKey"
+        )
+        nodes = (team_data.get("teams") or {}).get("nodes") or []
+        if not nodes:
+            raise RuntimeError(f"No team found with key {team_key!r}")
+        team_id = nodes[0]["id"]
+
+        # Active cycle
+        cycle_query = """
+        query ActiveCycle($teamId: String!) {
+          team(id: $teamId) {
+            activeCycle { id name number startsAt endsAt completedAt progress }
+          }
+        }
+        """
+        raw = await c.execute(cycle_query, {"teamId": team_id}, operation="ActiveCycle")
+        active = (raw.get("team") or {}).get("activeCycle")
+    if not active:
+        return json.dumps({"active_cycle": None, "team_key": team_key}, indent=2)
+    cycle_model = Cycle.model_validate(active)
+    return _to_json(cycle_model)
+
+
+async def issues_mine() -> str:
+    """hoja://issues/mine — viewer's open issues (Todo + In Progress + In Review)."""
+    async with _client() as c:
+        viewer_data = await c.execute(queries.VIEWER, operation="Viewer")
+        viewer_id = (viewer_data.get("viewer") or {}).get("id")
+        if not viewer_id:
+            raise RuntimeError("Could not resolve viewer id")
+
+        filt = {
+            "assignee": {"id": {"eq": viewer_id}},
+            "state": {"type": {"in": ["unstarted", "started"]}},
+        }
+        issues = await c.execute_list(
+            Issue,
+            queries.ISSUES_LIST,
+            {"filter": filt, "first": 50},
+            path=["issues"],
+            operation="Issues",
+        )
+    return _to_json(issues)
+
+
+async def issues_team(team_key: str) -> str:
+    """hoja://issues/team/{team_key} — open issues for a team."""
+    async with _client() as c:
+        filt = {
+            "team": {"key": {"eq": team_key}},
+            "state": {"type": {"in": ["unstarted", "started"]}},
+        }
+        try:
+            issues = await c.execute_list(
+                Issue,
+                queries.ISSUES_LIST,
+                {"filter": filt, "first": 50},
+                path=["issues"],
+                operation="Issues",
+            )
+        except HojaError as e:
+            raise RuntimeError(f"Could not list issues for team {team_key!r}: {e}") from e
+    return _to_json(issues)

hoja/mcp/server.py

@@ -0,0 +1,189 @@
+"""hoja-mcp — Model Context Protocol server for the hoja CLI.
+
+Run via the `hoja-mcp` console script (registered in pyproject.toml).
+Uses the official `mcp` Python SDK with FastMCP convenience layer.
+
+Exposes:
+  - 1 tool      : hoja_guide(topic) — teaches the agent how to use hoja
+  - 7 resources : read-only Linear context
+  - 6 prompts   : workflow templates
+
+By design the server does NOT expose mutation tools. Mutations happen via the
+`hoja` CLI in a shell — the tool's response payload and the prompt bodies
+both carry a behavioral reminder reinforcing this rule.
+
+STDIO TRANSPORT NOTE: When running on stdio (the default), stdout is reserved
+for the JSON-RPC stream. ALL logging must go to stderr. We configure that at
+the top of this module before any other import that might log.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+# Route logging to stderr BEFORE importing anything that might log.
+logging.basicConfig(
+    stream=sys.stderr,
+    level=logging.INFO,
+    format="[hoja-mcp] %(levelname)s %(message)s",
+)
+
+# Module-level imports for types used in tool/resource/prompt signatures.
+# The MCP SDK uses inspect.signature(..., eval_str=True) which resolves
+# stringified annotations against MODULE globals — so Topic/HojaGuide
+# must be importable at module level, not just inside _build_server().
+from . import prompts as _prompts  # noqa: E402
+from . import resources as _resources  # noqa: E402
+from .content import HojaGuide, Topic, load_topic  # noqa: E402
+
+
+def main() -> None:
+    """Entry point for the `hoja-mcp` console script.
+
+    Lazy-imports the MCP SDK so that `import hoja` (without the [mcp] extra)
+    does not fail at the top of this module. If the dep is missing, print a
+    friendly install hint to stderr and exit 2.
+    """
+    try:
+        from mcp.server.mcpserver import MCPServer  # noqa: F401
+    except ImportError:
+        sys.stderr.write(
+            "hoja-mcp requires the [mcp] extra.\nInstall with:\n  pip install 'hoja[mcp]'\n"
+        )
+        sys.exit(2)
+
+    _build_server().run()
+
+
+def _build_server():
+    """Wire tools, resources, and prompts onto an MCP v2 server."""
+    from mcp.server.mcpserver import MCPServer
+
+    from hoja import __version__
+
+    mcp = MCPServer(
+        name="hoja",
+        instructions=(
+            "Use this server to learn how to drive Linear from a shell using "
+            "the `hoja` CLI. Call `hoja_guide(topic)` BEFORE attempting "
+            "any Linear-related task. Read resources for read-only context. "
+            "Read prompts for multi-step workflow templates. Perform all "
+            "mutations via `hoja <command>` invoked through the Bash tool."
+        ),
+    )
+
+    # ------------------------------------------------------------------
+    # Tool — single teaching tool
+    # ------------------------------------------------------------------
+    @mcp.tool()
+    def hoja_guide(topic: Topic = Topic.OVERVIEW) -> HojaGuide:
+        """Return a guide on how to use the `hoja` CLI for a given topic.
+
+        ALWAYS call this BEFORE any Linear-related task. Then execute hoja
+        commands via the Bash tool. Do NOT write Python wrappers around the
+        Linear GraphQL API — hoja is the supported interface.
+
+        Available topics:
+          - overview         — when to reach for hoja; behavioral rules
+          - commands         — full command tree with examples
+          - workflows        — common multi-step patterns
+          - filters          — `issue list` filter DSL
+          - output-formats   — when to use --output json vs human vs ids
+          - examples         — copy-pasteable recipes
+        """
+        return load_topic(topic)
+
+    # ------------------------------------------------------------------
+    # Resources — read-only Linear context
+    # ------------------------------------------------------------------
+    @mcp.resource("hoja://me", name="viewer", description="Currently-authenticated Linear user.")
+    async def res_me() -> str:
+        return await _resources.viewer()
+
+    @mcp.resource(
+        "hoja://issue/{id}",
+        name="issue",
+        description="Full Linear issue by identifier (e.g. ENG-35), including comments, labels, subscribers.",
+    )
+    async def res_issue(id: str) -> str:
+        return await _resources.issue(id)
+
+    @mcp.resource(
+        "hoja://team/{key}",
+        name="team",
+        description="Team detail + workflow states + members for a team key (e.g. ENG).",
+    )
+    async def res_team(key: str) -> str:
+        return await _resources.team(key)
+
+    @mcp.resource(
+        "hoja://project/{id_or_slug}",
+        name="project",
+        description="Linear project by id or slug, including lead, creator, members.",
+    )
+    async def res_project(id_or_slug: str) -> str:
+        return await _resources.project(id_or_slug)
+
+    @mcp.resource(
+        "hoja://cycle/current/{team_key}",
+        name="cycle-current",
+        description="Active cycle for a team. Returns {active_cycle: null} when none.",
+    )
+    async def res_cycle(team_key: str) -> str:
+        return await _resources.cycle_current(team_key)
+
+    @mcp.resource(
+        "hoja://issues/mine",
+        name="issues-mine",
+        description="Open issues assigned to the viewer (Todo + In Progress).",
+    )
+    async def res_issues_mine() -> str:
+        return await _resources.issues_mine()
+
+    @mcp.resource(
+        "hoja://issues/team/{team_key}",
+        name="issues-team",
+        description="Open issues for a team (Todo + In Progress).",
+    )
+    async def res_issues_team(team_key: str) -> str:
+        return await _resources.issues_team(team_key)
+
+    # ------------------------------------------------------------------
+    # Prompts — workflow templates
+    # ------------------------------------------------------------------
+    @mcp.prompt(description="Triage unassigned issues for a team — step-by-step shell commands.")
+    def triage(team_key: str) -> str:
+        return _prompts.triage(team_key)
+
+    @mcp.prompt(description="Generate a daily standup report from viewer's recent activity.")
+    def daily_standup() -> str:
+        return _prompts.daily_standup()
+
+    @mcp.prompt(description="Create an issue from an error trace, with duplicate-search step.")
+    def create_from_error(error_text: str, team_key: str, priority: int = 3) -> str:
+        return _prompts.create_from_error(error_text, team_key, priority)
+
+    @mcp.prompt(description="Hand off an issue to another teammate in 3 commands.")
+    def hand_off(issue_id: str, to_user: str, note: str = "") -> str:
+        return _prompts.hand_off(issue_id, to_user, note)
+
+    @mcp.prompt(
+        description="Review the current cycle for a team — done/in-progress/blockers/stale."
+    )
+    def cycle_review(team_key: str) -> str:
+        return _prompts.cycle_review(team_key)
+
+    @mcp.prompt(description="Deep-dive investigation of a single issue.")
+    def issue_investigate(issue_id: str) -> str:
+        return _prompts.issue_investigate(issue_id)
+
+    logging.info(
+        "hoja-mcp v%s ready (tools=1, resources=7, prompts=6)",
+        __version__,
+    )
+    return mcp
+
+
+if __name__ == "__main__":
+    main()