feat(fable-mcp): implement FableClient, all tool modules, and server.py

- client.py: async httpx wrapper, FableAPIError, stream_get() SSE generator,
  singleton init_client()/get_client() and _reset_client() for tests
- tools/: notes, tasks, projects, milestones, search, chat — thin async
  functions that accept FableClient and call Fable REST endpoints
- server.py: FastMCP entry point with 20 tools registered via @mcp.tool(),
  each opening a fresh FableClient context per call; validates env vars at startup
- tests: 34 tests covering client HTTP behaviour, error handling, singleton,
  SSE streaming, and all tool modules

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fable-mcp/fable_mcp/tools/chat.py

@@ -0,0 +1,75 @@
+"""MCP tools for Fable chat — create conversations and stream responses."""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from fable_mcp.client import FableClient
+
+
+async def list_conversations(
+    client: FableClient,
+    *,
+    limit: int = 20,
+    offset: int = 0,
+) -> dict[str, Any]:
+    """List MCP chat conversations."""
+    params: dict[str, Any] = {"limit": limit, "offset": offset, "type": "mcp"}
+    return await client.get("/api/chat/conversations", params=params)
+
+
+async def send_message(
+    client: FableClient,
+    *,
+    message: str,
+    conversation_id: str | None = None,
+    think: bool = False,
+) -> dict[str, Any]:
+    """Send a message to Fable and return the full assistant response.
+
+    Creates a new MCP conversation if conversation_id is None.
+    Streams the SSE response and accumulates token chunks into a single string.
+
+    Returns:
+        Dict with:
+          - "conversation_id": str
+          - "response": str (full assistant message)
+          - "tool_calls": list of any tool_call events observed
+    """
+    if conversation_id is None:
+        conv = await client.post(
+            "/api/chat/conversations",
+            json={"conversation_type": "mcp"},
+        )
+        conversation_id = conv["id"]
+
+    # Build SSE stream URL with message as query param
+    params: dict[str, Any] = {"message": message}
+    if think:
+        params["think"] = "true"
+
+    tokens: list[str] = []
+    tool_calls: list[Any] = []
+
+    stream_path = f"/api/chat/conversations/{conversation_id}/stream"
+    async for raw_line in client.stream_get(stream_path, params=params):
+        if not raw_line.startswith("data: "):
+            continue
+        payload_str = raw_line[len("data: "):]
+        try:
+            event = json.loads(payload_str)
+        except json.JSONDecodeError:
+            continue
+        event_type = event.get("type")
+        if event_type == "token":
+            tokens.append(event.get("content", ""))
+        elif event_type == "tool_call":
+            tool_calls.append(event)
+        elif event_type == "done":
+            break
+
+    return {
+        "conversation_id": conversation_id,
+        "response": "".join(tokens),
+        "tool_calls": tool_calls,
+    }

fable-mcp/fable_mcp/tools/milestones.py

@@ -0,0 +1,53 @@
+"""MCP tools for Fable milestones."""
+from __future__ import annotations
+
+from typing import Any
+
+from fable_mcp.client import FableClient
+
+
+async def list_milestones(client: FableClient, *, project_id: int) -> dict[str, Any]:
+    """List milestones for a project."""
+    return await client.get(f"/api/projects/{project_id}/milestones")
+
+
+async def create_milestone(
+    client: FableClient,
+    *,
+    project_id: int,
+    title: str,
+    description: str = "",
+    status: str = "active",
+) -> dict[str, Any]:
+    """Create a milestone within a project."""
+    payload: dict[str, Any] = {
+        "title": title,
+        "description": description,
+        "status": status,
+    }
+    return await client.post(f"/api/projects/{project_id}/milestones", json=payload)
+
+
+async def update_milestone(
+    client: FableClient,
+    *,
+    project_id: int,
+    milestone_id: int,
+    title: str | None = None,
+    description: str | None = None,
+    status: str | None = None,
+    order_index: int | None = None,
+) -> dict[str, Any]:
+    """Update an existing milestone."""
+    payload: dict[str, Any] = {}
+    if title is not None:
+        payload["title"] = title
+    if description is not None:
+        payload["description"] = description
+    if status is not None:
+        payload["status"] = status
+    if order_index is not None:
+        payload["order_index"] = order_index
+    return await client.patch(
+        f"/api/projects/{project_id}/milestones/{milestone_id}", json=payload
+    )

fable-mcp/fable_mcp/tools/notes.py

@@ -0,0 +1,72 @@
+"""MCP tools for Fable notes."""
+from __future__ import annotations
+
+from typing import Any
+
+from fable_mcp.client import FableClient
+
+
+async def list_notes(
+    client: FableClient,
+    *,
+    limit: int = 20,
+    offset: int = 0,
+    tag: str | None = None,
+    search: str | None = None,
+) -> dict[str, Any]:
+    """List notes with optional filtering."""
+    params: dict[str, Any] = {"limit": limit, "offset": offset}
+    if tag:
+        params["tag"] = tag
+    if search:
+        params["search"] = search
+    return await client.get("/api/notes", params=params)
+
+
+async def get_note(client: FableClient, *, note_id: int) -> dict[str, Any]:
+    """Fetch a single note by ID."""
+    return await client.get(f"/api/notes/{note_id}")
+
+
+async def create_note(
+    client: FableClient,
+    *,
+    title: str,
+    body: str = "",
+    tags: list[str] | None = None,
+    project_id: int | None = None,
+) -> dict[str, Any]:
+    """Create a new note."""
+    payload: dict[str, Any] = {"title": title, "body": body}
+    if tags is not None:
+        payload["tags"] = tags
+    if project_id is not None:
+        payload["project_id"] = project_id
+    return await client.post("/api/notes", json=payload)
+
+
+async def update_note(
+    client: FableClient,
+    *,
+    note_id: int,
+    title: str | None = None,
+    body: str | None = None,
+    tags: list[str] | None = None,
+    project_id: int | None = None,
+) -> dict[str, Any]:
+    """Update an existing note."""
+    payload: dict[str, Any] = {}
+    if title is not None:
+        payload["title"] = title
+    if body is not None:
+        payload["body"] = body
+    if tags is not None:
+        payload["tags"] = tags
+    if project_id is not None:
+        payload["project_id"] = project_id
+    return await client.patch(f"/api/notes/{note_id}", json=payload)
+
+
+async def delete_note(client: FableClient, *, note_id: int) -> None:
+    """Delete a note by ID."""
+    await client.delete(f"/api/notes/{note_id}")

fable-mcp/fable_mcp/tools/projects.py

@@ -0,0 +1,59 @@
+"""MCP tools for Fable projects."""
+from __future__ import annotations
+
+from typing import Any
+
+from fable_mcp.client import FableClient
+
+
+async def list_projects(client: FableClient) -> dict[str, Any]:
+    """List all projects for the authenticated user."""
+    return await client.get("/api/projects")
+
+
+async def get_project(client: FableClient, *, project_id: int) -> dict[str, Any]:
+    """Fetch a project by ID (includes milestone summary)."""
+    return await client.get(f"/api/projects/{project_id}")
+
+
+async def create_project(
+    client: FableClient,
+    *,
+    title: str,
+    description: str = "",
+    goal: str | None = None,
+    status: str = "active",
+    color: str | None = None,
+) -> dict[str, Any]:
+    """Create a new project."""
+    payload: dict[str, Any] = {"title": title, "description": description, "status": status}
+    if goal is not None:
+        payload["goal"] = goal
+    if color is not None:
+        payload["color"] = color
+    return await client.post("/api/projects", json=payload)
+
+
+async def update_project(
+    client: FableClient,
+    *,
+    project_id: int,
+    title: str | None = None,
+    description: str | None = None,
+    goal: str | None = None,
+    status: str | None = None,
+    color: str | None = None,
+) -> dict[str, Any]:
+    """Update an existing project."""
+    payload: dict[str, Any] = {}
+    if title is not None:
+        payload["title"] = title
+    if description is not None:
+        payload["description"] = description
+    if goal is not None:
+        payload["goal"] = goal
+    if status is not None:
+        payload["status"] = status
+    if color is not None:
+        payload["color"] = color
+    return await client.patch(f"/api/projects/{project_id}", json=payload)

fable-mcp/fable_mcp/tools/search.py

@@ -0,0 +1,30 @@
+"""MCP tool for semantic search across Fable notes and tasks."""
+from __future__ import annotations
+
+from typing import Any
+
+from fable_mcp.client import FableClient
+
+
+async def search(
+    client: FableClient,
+    *,
+    q: str,
+    content_type: str = "all",
+    limit: int = 10,
+) -> dict[str, Any]:
+    """Semantic search over notes and/or tasks.
+
+    Args:
+        q: Search query string.
+        content_type: One of "note", "task", or "all" (default).
+        limit: Maximum number of results to return.
+
+    Returns:
+        Dict with "results" list and "total" count.
+        Each result has: id, title, body, is_task, tags, similarity.
+    """
+    params: dict[str, Any] = {"q": q, "limit": limit}
+    if content_type != "all":
+        params["content_type"] = content_type
+    return await client.get("/api/search", params=params)

fable-mcp/fable_mcp/tools/tasks.py

@@ -0,0 +1,93 @@
+"""MCP tools for Fable tasks."""
+from __future__ import annotations
+
+from typing import Any
+
+from fable_mcp.client import FableClient
+
+
+async def list_tasks(
+    client: FableClient,
+    *,
+    limit: int = 20,
+    offset: int = 0,
+    status: str | None = None,
+    project_id: int | None = None,
+) -> dict[str, Any]:
+    """List tasks with optional filtering."""
+    params: dict[str, Any] = {"limit": limit, "offset": offset}
+    if status:
+        params["status"] = status
+    if project_id is not None:
+        params["project_id"] = project_id
+    return await client.get("/api/tasks", params=params)
+
+
+async def get_task(client: FableClient, *, task_id: int) -> dict[str, Any]:
+    """Fetch a single task by ID (includes parent_title)."""
+    return await client.get(f"/api/tasks/{task_id}")
+
+
+async def create_task(
+    client: FableClient,
+    *,
+    title: str,
+    body: str = "",
+    status: str = "todo",
+    priority: str | None = None,
+    project_id: int | None = None,
+    milestone_id: int | None = None,
+    parent_id: int | None = None,
+    tags: list[str] | None = None,
+) -> dict[str, Any]:
+    """Create a new task."""
+    payload: dict[str, Any] = {"title": title, "body": body, "status": status}
+    if priority is not None:
+        payload["priority"] = priority
+    if project_id is not None:
+        payload["project_id"] = project_id
+    if milestone_id is not None:
+        payload["milestone_id"] = milestone_id
+    if parent_id is not None:
+        payload["parent_id"] = parent_id
+    if tags is not None:
+        payload["tags"] = tags
+    return await client.post("/api/tasks", json=payload)
+
+
+async def update_task(
+    client: FableClient,
+    *,
+    task_id: int,
+    title: str | None = None,
+    body: str | None = None,
+    status: str | None = None,
+    priority: str | None = None,
+    project_id: int | None = None,
+    milestone_id: int | None = None,
+) -> dict[str, Any]:
+    """Update an existing task."""
+    payload: dict[str, Any] = {}
+    if title is not None:
+        payload["title"] = title
+    if body is not None:
+        payload["body"] = body
+    if status is not None:
+        payload["status"] = status
+    if priority is not None:
+        payload["priority"] = priority
+    if project_id is not None:
+        payload["project_id"] = project_id
+    if milestone_id is not None:
+        payload["milestone_id"] = milestone_id
+    return await client.patch(f"/api/tasks/{task_id}", json=payload)
+
+
+async def add_task_log(
+    client: FableClient,
+    *,
+    task_id: int,
+    body: str,
+) -> dict[str, Any]:
+    """Append a log entry to a task."""
+    return await client.post(f"/api/tasks/{task_id}/logs", json={"body": body})