feat(mcp): replace briefing tools with journal tools
The MCP was still calling /api/briefing/* endpoints I deleted in the
journal hard-cut. Replaced the briefing tool surface with a journal
equivalent so external MCP clients can inspect and control the journal
the same way they could the briefing.
Changes:
- New fable_mcp/tools/journal.py — helpers for /api/journal/* endpoints
- Delete fable_mcp/tools/briefing.py — RSS endpoints are gone too
- server.py: drop fable_list_rss_feeds, fable_add_rss_feed, fable_remove_rss_feed,
fable_list_briefings, fable_get_today_briefing, fable_get_briefing_messages,
fable_trigger_briefing, fable_reset_today_briefing
- server.py: add fable_get_today_journal, fable_get_journal_day,
fable_list_journal_days, fable_trigger_journal_prep, fable_get_journal_config,
fable_list_moments
- server.py: fable_get_conversation now points at journal.get_conversation
(same /api/chat/conversations/{id} endpoint, just lives under journal helpers)
- Update _INSTRUCTIONS to describe the journal model (replacing the RSS/briefing
section) — explains the daily prep, moments, day payloads
- Update top-line docstring: "Fable Assistant" → "Fable Scribe"
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
+127
-135
@@ -1,16 +1,16 @@
|
||||
"""Fable MCP server — exposes Fable Assistant as MCP tools via stdio transport."""
|
||||
"""Fable MCP server — exposes Fable Scribe as MCP tools via stdio transport."""
|
||||
from __future__ import annotations
|
||||
|
||||
from mcp.server.fastmcp import FastMCP
|
||||
from dotenv import load_dotenv
|
||||
|
||||
from fable_mcp.client import FableClient
|
||||
from fable_mcp.tools import notes, tasks, projects, milestones, search, chat, admin, briefing
|
||||
from fable_mcp.tools import notes, tasks, projects, milestones, search, chat, admin, journal
|
||||
|
||||
load_dotenv()
|
||||
|
||||
_INSTRUCTIONS = """
|
||||
Fable Assistant is a self-hosted second-brain and project management system with LLM integration.
|
||||
Fabled Scribe is a self-hosted second-brain and project management system with LLM integration.
|
||||
|
||||
## Data model
|
||||
|
||||
@@ -68,10 +68,19 @@ Use the direct CRUD tools when:
|
||||
Use `fable_add_task_log` to append time-stamped progress notes to a task without overwriting
|
||||
its main body. Suitable for recording work sessions, decisions, or status updates over time.
|
||||
|
||||
## RSS / Briefing
|
||||
## Journal
|
||||
|
||||
Fable runs a daily briefing that summarises tasks, calendar events, and RSS feed items.
|
||||
Use `fable_add_rss_feed` / `fable_remove_rss_feed` to manage the feeds included in that briefing.
|
||||
Fable Scribe runs a per-day Journal — a conversational surface where the user narrates
|
||||
their day. Each day has its own conversation. The first assistant message in a day's
|
||||
conversation is the **daily prep**: an LLM-generated briefing covering today's tasks,
|
||||
calendar events, weather, active projects, and recent journal context. Subsequent turns
|
||||
are user/assistant journaling exchanges; the LLM may emit **Moments** (small structured
|
||||
extractions) via the `record_moment` tool during the conversation.
|
||||
|
||||
Use `fable_get_today_journal` to inspect today's prep + conversation. Use
|
||||
`fable_get_journal_day` for past days. Use `fable_list_moments` to query the structured
|
||||
journal extractions across days. Use `fable_trigger_journal_prep` to force-regenerate
|
||||
today's prep prose.
|
||||
|
||||
## Admin logs
|
||||
|
||||
@@ -582,148 +591,131 @@ async def fable_get_app_logs(
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Briefing / RSS
|
||||
# Journal — daily prep, day payloads, moments
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@mcp.tool()
|
||||
async def fable_list_rss_feeds() -> dict:
|
||||
"""List all RSS/Atom feeds configured in Fable for the current user.
|
||||
async def fable_get_today_journal() -> dict:
|
||||
"""Fetch today's Journal day payload.
|
||||
|
||||
Returns id, title, url, category, and last_fetched_at for each feed.
|
||||
These feeds are summarised in the user's daily briefing.
|
||||
Creates today's journal conversation and generates the daily prep
|
||||
message if neither exists yet. Returns:
|
||||
{
|
||||
"day_date": "YYYY-MM-DD",
|
||||
"conversation": { id, title, conversation_type, day_date, ... },
|
||||
"messages": [ ... ordered list of messages ... ]
|
||||
}
|
||||
|
||||
The first assistant message is the daily prep — a conversational
|
||||
opener generated by the LLM from gathered tasks/events/weather/
|
||||
projects/recent moments/open threads. Its ``msg_metadata.sections``
|
||||
carries the underlying structured data for inspection.
|
||||
"""
|
||||
async with FableClient() as client:
|
||||
return await briefing.list_rss_feeds(client)
|
||||
return await journal.get_today_journal(client)
|
||||
|
||||
|
||||
@mcp.tool()
|
||||
async def fable_add_rss_feed(
|
||||
url: str,
|
||||
title: str = "",
|
||||
category: str = "",
|
||||
async def fable_get_journal_day(iso_date: str) -> dict:
|
||||
"""Fetch a specific day's Journal payload by ISO date.
|
||||
|
||||
Args:
|
||||
iso_date: YYYY-MM-DD format date.
|
||||
|
||||
Returns the same shape as fable_get_today_journal. If no journal
|
||||
exists for that day, ``conversation`` and ``messages`` will be
|
||||
null/empty respectively.
|
||||
"""
|
||||
async with FableClient() as client:
|
||||
return await journal.get_journal_day(client, iso_date=iso_date)
|
||||
|
||||
|
||||
@mcp.tool()
|
||||
async def fable_list_journal_days() -> dict:
|
||||
"""List dates that have journal content for the current user, newest first.
|
||||
|
||||
Returns ``{"days": ["YYYY-MM-DD", ...]}``. Use these dates to query
|
||||
specific days via ``fable_get_journal_day``.
|
||||
"""
|
||||
async with FableClient() as client:
|
||||
return await journal.list_journal_days(client)
|
||||
|
||||
|
||||
@mcp.tool()
|
||||
async def fable_trigger_journal_prep(iso_date: str = "") -> dict:
|
||||
"""Force-regenerate the daily prep prose for today (or a specific day).
|
||||
|
||||
The prep is the first assistant message in a day's journal — a
|
||||
conversational LLM-generated briefing built from tasks/events/weather/
|
||||
projects/recent moments/open threads. Use this to iterate on the prep
|
||||
prompt or refresh after data changes.
|
||||
|
||||
Args:
|
||||
iso_date: Optional YYYY-MM-DD. If empty, regenerates today.
|
||||
|
||||
Returns ``{"ok": true, "message_id": ...}``.
|
||||
"""
|
||||
async with FableClient() as client:
|
||||
return await journal.trigger_journal_prep(
|
||||
client, iso_date=iso_date or None,
|
||||
)
|
||||
|
||||
|
||||
@mcp.tool()
|
||||
async def fable_get_journal_config() -> dict:
|
||||
"""Fetch the user's journal config.
|
||||
|
||||
Includes prep schedule (prep_enabled / prep_hour / prep_minute),
|
||||
day rollover hour, phase boundaries, and any locations / temp_unit
|
||||
used for the prep's weather section.
|
||||
"""
|
||||
async with FableClient() as client:
|
||||
return await journal.get_journal_config(client)
|
||||
|
||||
|
||||
@mcp.tool()
|
||||
async def fable_list_moments(
|
||||
query: str = "",
|
||||
person_id: int = 0,
|
||||
place_id: int = 0,
|
||||
tag: str = "",
|
||||
date_from: str = "",
|
||||
date_to: str = "",
|
||||
pinned_only: bool = False,
|
||||
limit: int = 50,
|
||||
) -> dict:
|
||||
"""Add an RSS or Atom feed to Fable's daily briefing.
|
||||
"""Search/list journal Moments — small structured extractions the LLM emits during journaling.
|
||||
|
||||
All filters are optional and combinable. Without a query, returns
|
||||
moments ordered by occurred_at DESC. With a query, returns
|
||||
semantically-ranked moments above the similarity threshold.
|
||||
|
||||
Args:
|
||||
url: The RSS/Atom feed URL (required).
|
||||
title: Optional display name. If omitted, auto-populated from feed metadata.
|
||||
category: Optional category label to group feeds (e.g. "news", "tech", "finance").
|
||||
query: Optional semantic query string.
|
||||
person_id: Filter to moments mentioning this person (0 = no filter).
|
||||
place_id: Filter to moments mentioning this place (0 = no filter).
|
||||
tag: Filter to moments with this tag.
|
||||
date_from: ISO YYYY-MM-DD lower bound (inclusive).
|
||||
date_to: ISO YYYY-MM-DD upper bound (inclusive).
|
||||
pinned_only: If True, only return pinned moments.
|
||||
limit: Max results, default 50.
|
||||
|
||||
Returns the created feed object including its assigned id.
|
||||
Returns ``{"moments": [...]}`` where each moment has id, day_date,
|
||||
occurred_at, content, raw_excerpt, tags, people, places, task_ids,
|
||||
note_ids, pinned, and (when query set) score.
|
||||
"""
|
||||
async with FableClient() as client:
|
||||
return await briefing.add_rss_feed(
|
||||
return await journal.list_moments(
|
||||
client,
|
||||
url=url,
|
||||
title=title or None,
|
||||
category=category or None,
|
||||
)
|
||||
|
||||
|
||||
@mcp.tool()
|
||||
async def fable_remove_rss_feed(feed_id: int) -> dict:
|
||||
"""Remove an RSS feed from Fable by its ID."""
|
||||
async with FableClient() as client:
|
||||
return await briefing.remove_rss_feed(client, feed_id=feed_id)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Briefing introspection & control
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@mcp.tool()
|
||||
async def fable_list_briefings() -> dict:
|
||||
"""List the user's briefing conversations, newest first.
|
||||
|
||||
Each briefing has an associated date and conversation id. Use
|
||||
``fable_get_briefing_messages`` or ``fable_get_conversation`` with
|
||||
the id to pull the actual briefing text and tool-call receipts.
|
||||
|
||||
Returns a dict with a ``conversations`` list.
|
||||
"""
|
||||
async with FableClient() as client:
|
||||
return await briefing.list_briefing_conversations(client)
|
||||
|
||||
|
||||
@mcp.tool()
|
||||
async def fable_get_today_briefing() -> dict:
|
||||
"""Fetch today's briefing conversation, creating it if needed.
|
||||
|
||||
Returns the full conversation object including all messages — the
|
||||
scheduled briefing assistant turns, any tool calls the agentic path
|
||||
made, and any chat replies the user has sent in the briefing thread.
|
||||
|
||||
Use this to inspect what a briefing actually said (and what tool
|
||||
results grounded it) without having to query by id.
|
||||
"""
|
||||
async with FableClient() as client:
|
||||
return await briefing.get_today_briefing(client)
|
||||
|
||||
|
||||
@mcp.tool()
|
||||
async def fable_get_briefing_messages(conversation_id: int) -> dict:
|
||||
"""Fetch all messages for a specific briefing conversation.
|
||||
|
||||
Args:
|
||||
conversation_id: The briefing conversation id from fable_list_briefings.
|
||||
|
||||
Returns a dict with a ``messages`` list. Each message includes
|
||||
role, content, tool_calls (with results), and metadata — the
|
||||
metadata carries ``briefing_slot`` tags on agentic briefing turns.
|
||||
"""
|
||||
async with FableClient() as client:
|
||||
return await briefing.get_briefing_messages(
|
||||
client, conversation_id=conversation_id,
|
||||
)
|
||||
|
||||
|
||||
@mcp.tool()
|
||||
async def fable_trigger_briefing(slot: str = "compilation") -> dict:
|
||||
"""Manually run a briefing slot for the current user.
|
||||
|
||||
Fires the same data refresh the scheduler does (RSS, weather),
|
||||
runs the agentic briefing pipeline, and writes the result into
|
||||
today's briefing conversation. Use this to test prompt changes
|
||||
without waiting for the next scheduled slot.
|
||||
|
||||
Args:
|
||||
slot: One of ``compilation`` (full morning, default), ``morning``,
|
||||
``midday``, or ``afternoon``.
|
||||
|
||||
Returns a dict with ``conversation_id``, ``message_id``, and ``slot``.
|
||||
"""
|
||||
async with FableClient() as client:
|
||||
return await briefing.trigger_briefing(client, slot=slot)
|
||||
|
||||
|
||||
@mcp.tool()
|
||||
async def fable_reset_today_briefing(run_compilation: bool = True) -> dict:
|
||||
"""Wipe today's briefing and (optionally) regenerate from scratch.
|
||||
|
||||
Deletes every message in today's briefing conversation — the
|
||||
conversation row itself is kept so its id stays stable for any
|
||||
open UI sessions. If ``run_compilation`` is True (the default),
|
||||
immediately fires the compilation slot afterward so a fresh
|
||||
briefing lands in place of the deleted content.
|
||||
|
||||
Use this when iterating on briefing prompts or tools and you want
|
||||
to start from a clean slate rather than append another slot update
|
||||
on top of stale output.
|
||||
|
||||
Args:
|
||||
run_compilation: When True, fire ``POST /api/briefing/trigger``
|
||||
for the ``compilation`` slot immediately after wiping.
|
||||
Set False to only wipe without regenerating.
|
||||
|
||||
Returns a dict with ``reset`` (the delete result: deleted count +
|
||||
conversation id) and ``triggered`` (the new message payload, or
|
||||
null if regeneration was skipped).
|
||||
"""
|
||||
async with FableClient() as client:
|
||||
return await briefing.reset_today_briefing(
|
||||
client, run_compilation=run_compilation,
|
||||
query=query or None,
|
||||
person_id=person_id if person_id else None,
|
||||
place_id=place_id if place_id else None,
|
||||
tag=tag or None,
|
||||
date_from=date_from or None,
|
||||
date_to=date_to or None,
|
||||
pinned_only=pinned_only,
|
||||
limit=limit,
|
||||
)
|
||||
|
||||
|
||||
@@ -734,18 +726,18 @@ async def fable_reset_today_briefing(run_compilation: bool = True) -> dict:
|
||||
|
||||
@mcp.tool()
|
||||
async def fable_get_conversation(conversation_id: int) -> dict:
|
||||
"""Fetch any conversation (chat or briefing) with its full message list.
|
||||
"""Fetch any conversation (chat or journal) with its full message list.
|
||||
|
||||
Returns conversation metadata plus an ordered ``messages`` array.
|
||||
Each message includes role, content, tool_calls (with results),
|
||||
context_note_id, and msg_metadata. Tool calls are in the stored
|
||||
flat format: ``[{"function": name, "arguments": {...}, "result": {...}}]``.
|
||||
|
||||
Useful for debugging agentic briefings, inspecting chat history,
|
||||
or verifying that a tool actually ran with the expected arguments.
|
||||
Useful for inspecting journal preps, chat history, or verifying
|
||||
that a tool actually ran with the expected arguments.
|
||||
"""
|
||||
async with FableClient() as client:
|
||||
return await briefing.get_conversation(
|
||||
return await journal.get_conversation(
|
||||
client, conversation_id=conversation_id,
|
||||
)
|
||||
|
||||
|
||||
@@ -1,98 +0,0 @@
|
||||
"""MCP tools for Fable briefings and RSS feed management."""
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from fable_mcp.client import FableClient
|
||||
|
||||
|
||||
# ── RSS feeds ────────────────────────────────────────────────────────────────
|
||||
|
||||
async def list_rss_feeds(client: FableClient) -> dict[str, Any]:
|
||||
"""List the user's RSS feeds."""
|
||||
return await client.get("/api/briefing/feeds")
|
||||
|
||||
|
||||
async def add_rss_feed(
|
||||
client: FableClient,
|
||||
*,
|
||||
url: str,
|
||||
title: str | None = None,
|
||||
category: str | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Add a new RSS feed. Title is optional — auto-populated from feed metadata."""
|
||||
payload: dict[str, Any] = {"url": url}
|
||||
if title:
|
||||
payload["title"] = title
|
||||
if category:
|
||||
payload["category"] = category
|
||||
return await client.post("/api/briefing/feeds", json=payload)
|
||||
|
||||
|
||||
async def remove_rss_feed(client: FableClient, *, feed_id: int) -> dict[str, Any]:
|
||||
"""Remove an RSS feed by ID."""
|
||||
return await client.delete(f"/api/briefing/feeds/{feed_id}")
|
||||
|
||||
|
||||
# ── Briefings ────────────────────────────────────────────────────────────────
|
||||
|
||||
async def list_briefing_conversations(client: FableClient) -> dict[str, Any]:
|
||||
"""List the user's briefing conversations, newest first."""
|
||||
return await client.get("/api/briefing/conversations")
|
||||
|
||||
|
||||
async def get_today_briefing(client: FableClient) -> dict[str, Any]:
|
||||
"""Fetch today's briefing conversation with all messages."""
|
||||
return await client.get("/api/briefing/conversations/today")
|
||||
|
||||
|
||||
async def get_briefing_messages(
|
||||
client: FableClient,
|
||||
*,
|
||||
conversation_id: int,
|
||||
) -> dict[str, Any]:
|
||||
"""Fetch messages for a specific briefing conversation."""
|
||||
return await client.get(f"/api/briefing/conversations/{conversation_id}/messages")
|
||||
|
||||
|
||||
async def trigger_briefing(
|
||||
client: FableClient,
|
||||
*,
|
||||
slot: str = "compilation",
|
||||
) -> dict[str, Any]:
|
||||
"""Manually trigger a briefing slot — fires data refresh and runs the pipeline.
|
||||
|
||||
Slot is one of: compilation (full morning), morning, midday, afternoon.
|
||||
"""
|
||||
return await client.post("/api/briefing/trigger", json={"slot": slot})
|
||||
|
||||
|
||||
async def reset_today_briefing(
|
||||
client: FableClient,
|
||||
*,
|
||||
run_compilation: bool = True,
|
||||
) -> dict[str, Any]:
|
||||
"""Delete all messages in today's briefing and optionally regenerate.
|
||||
|
||||
Wipes the messages in today's briefing conversation (keeping the
|
||||
conversation row), then, if ``run_compilation`` is True, fires the
|
||||
compilation slot so a fresh briefing lands in its place.
|
||||
"""
|
||||
reset = await client.post("/api/briefing/reset-today")
|
||||
if not run_compilation:
|
||||
return {"reset": reset, "triggered": None}
|
||||
triggered = await client.post(
|
||||
"/api/briefing/trigger", json={"slot": "compilation"}
|
||||
)
|
||||
return {"reset": reset, "triggered": triggered}
|
||||
|
||||
|
||||
# ── Generic conversations ───────────────────────────────────────────────────
|
||||
|
||||
async def get_conversation(
|
||||
client: FableClient,
|
||||
*,
|
||||
conversation_id: int,
|
||||
) -> dict[str, Any]:
|
||||
"""Fetch any conversation (chat or briefing) with all messages and tool calls."""
|
||||
return await client.get(f"/api/chat/conversations/{conversation_id}")
|
||||
@@ -0,0 +1,96 @@
|
||||
"""MCP tools for inspecting and controlling the Fable Scribe Journal."""
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from fable_mcp.client import FableClient
|
||||
|
||||
|
||||
# ── Day payloads ─────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
async def get_today_journal(client: FableClient) -> dict[str, Any]:
|
||||
"""Fetch today's journal day payload (creates today's conversation + prep if needed)."""
|
||||
return await client.get("/api/journal/today")
|
||||
|
||||
|
||||
async def get_journal_day(client: FableClient, *, iso_date: str) -> dict[str, Any]:
|
||||
"""Fetch a specific day's journal payload by ISO date (YYYY-MM-DD)."""
|
||||
return await client.get(f"/api/journal/day/{iso_date}")
|
||||
|
||||
|
||||
async def list_journal_days(client: FableClient) -> dict[str, Any]:
|
||||
"""List dates that have journal content for the current user."""
|
||||
return await client.get("/api/journal/days")
|
||||
|
||||
|
||||
# ── Daily prep ───────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
async def trigger_journal_prep(
|
||||
client: FableClient,
|
||||
*,
|
||||
iso_date: str | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Force-regenerate the daily prep for today (or a specific day)."""
|
||||
payload: dict[str, Any] = {}
|
||||
if iso_date:
|
||||
payload["date"] = iso_date
|
||||
return await client.post("/api/journal/trigger-prep", json=payload)
|
||||
|
||||
|
||||
# ── Config ───────────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
async def get_journal_config(client: FableClient) -> dict[str, Any]:
|
||||
"""Fetch the user's journal config (prep schedule, day rollover, locations, etc.)."""
|
||||
return await client.get("/api/journal/config")
|
||||
|
||||
|
||||
# ── Moments ──────────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
async def list_moments(
|
||||
client: FableClient,
|
||||
*,
|
||||
query: str | None = None,
|
||||
person_id: int | None = None,
|
||||
place_id: int | None = None,
|
||||
tag: str | None = None,
|
||||
date_from: str | None = None,
|
||||
date_to: str | None = None,
|
||||
pinned_only: bool = False,
|
||||
limit: int = 50,
|
||||
) -> dict[str, Any]:
|
||||
"""List/search journal moments with optional filters.
|
||||
|
||||
All params are optional. Returns a dict with a ``moments`` array.
|
||||
"""
|
||||
params: dict[str, str] = {"limit": str(limit)}
|
||||
if query:
|
||||
params["query"] = query
|
||||
if person_id is not None:
|
||||
params["person_id"] = str(person_id)
|
||||
if place_id is not None:
|
||||
params["place_id"] = str(place_id)
|
||||
if tag:
|
||||
params["tag"] = tag
|
||||
if date_from:
|
||||
params["date_from"] = date_from
|
||||
if date_to:
|
||||
params["date_to"] = date_to
|
||||
if pinned_only:
|
||||
params["pinned_only"] = "true"
|
||||
return await client.get("/api/journal/moments", params=params)
|
||||
|
||||
|
||||
# ── Generic conversation access (still works for journal conversations) ───────
|
||||
|
||||
|
||||
async def get_conversation(
|
||||
client: FableClient,
|
||||
*,
|
||||
conversation_id: int,
|
||||
) -> dict[str, Any]:
|
||||
"""Fetch any conversation (chat or journal) with its full message list."""
|
||||
return await client.get(f"/api/chat/conversations/{conversation_id}")
|
||||
Reference in New Issue
Block a user