@unclick/mcp-server 0.2.5 → 0.3.1

package/dist/server.js

@@ -3,8 +3,82 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { CATALOG, TOOL_MAP, ENDPOINT_MAP } from "./catalog.js";
 import { createClient } from "./client.js";
-import { ADDITIONAL_HANDLERS } from "./tool-wiring.js";
+import { ADDITIONAL_TOOLS, ADDITIONAL_HANDLERS } from "./tool-wiring.js";
 import { LOCAL_CATALOG_HANDLERS } from "./local-catalog-handlers.js";
+import { MEMORY_HANDLERS } from "./memory/handlers.js";
+import { emitSignal } from "./signals/emit.js";
+import { createHash } from "node:crypto";
+// ─── Umami tool-usage tracking ──────────────────────────────────────────────
+//
+// Fires a fire-and-forget event to the self-hosted Umami instance every time
+// an agent actually invokes a tool. Lets Chris see which tools get used.
+// No-ops silently if UMAMI_WEBSITE_ID is not set (e.g. dev / local runs).
+// Never awaited so it cannot slow or break a tool call even if Umami is down.
+function trackToolCall(toolName) {
+    const websiteId = process.env.UMAMI_WEBSITE_ID;
+    if (!websiteId)
+        return;
+    const umamiUrl = process.env.UMAMI_URL ?? "https://analytics.unclick.world";
+    try {
+        void fetch(`${umamiUrl}/api/send`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "User-Agent": "unclick-mcp-server/1.0",
+            },
+            body: JSON.stringify({
+                type: "event",
+                payload: {
+                    website: websiteId,
+                    hostname: "unclick.world",
+                    url: "/api/mcp",
+                    name: "tool_call",
+                    data: { tool_name: toolName },
+                },
+            }),
+        }).catch(() => {
+            // swallow network / TLS errors
+        });
+    }
+    catch {
+        // swallow synchronous errors (e.g. malformed env)
+    }
+}
+function currentApiKeyHash() {
+    const configuredHash = process.env.UNCLICK_API_KEY_HASH?.trim();
+    if (configuredHash)
+        return configuredHash;
+    const apiKey = process.env.UNCLICK_API_KEY?.trim();
+    if (!apiKey)
+        return null;
+    return createHash("sha256").update(apiKey).digest("hex");
+}
+function failureSummary(toolName, result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const record = result;
+    if (typeof record.error === "string" && record.error.trim()) {
+        return `${toolName}: ${record.error.trim()}`;
+    }
+    if (typeof record.headline === "string" && /\bfailed\b/i.test(record.headline)) {
+        return `${toolName}: ${record.headline}`;
+    }
+    return null;
+}
+function signalToolFailure(toolName, result) {
+    const apiKeyHash = currentApiKeyHash();
+    const summary = failureSummary(toolName, result);
+    if (!apiKeyHash || !summary)
+        return;
+    void emitSignal({
+        apiKeyHash,
+        tool: toolName,
+        action: "failed",
+        severity: "action_needed",
+        summary: summary.slice(0, 500),
+        payload: { source: "mcp-server" },
+    });
+}
 // ─── Search helper ──────────────────────────────────────────────────────────
 function searchTools(query, category) {
     const q = query.toLowerCase();
@@ -31,18 +105,20 @@ function formatToolSummary(tool) {
     ].join("\n");
 }
 // ─── MCP Tool definitions ───────────────────────────────────────────────────
-const META_TOOLS = [
+// Internal tools: still callable for backwards compatibility, but not advertised
+// to reduce noise in the tool list. Users who know the names can still invoke them.
+const INTERNAL_TOOLS = [
     {
         name: "unclick_search",
         description: "Search the UnClick tool marketplace by keyword or description. " +
             "Use this to discover which tools are available for a task. " +
-            "Example: 'I need to resize an image' → returns the image tool with its endpoints.",
+            "Example: 'I need to resize an image' returns the image tool with its endpoints.",
         inputSchema: {
             type: "object",
             properties: {
                 query: {
                     type: "string",
-                    description: "Search term — describe what you want to do",
+                    description: "Search term -- describe what you want to do",
                 },
                 category: {
                     type: "string",
@@ -106,6 +182,504 @@ const META_TOOLS = [
         },
     },
 ];
+// Visible tools: the 5 core memory tools shown in the MCP tool list. These are
+// the only tools users see in their AI client. Old names (get_startup_context,
+// add_fact, write_session_summary, set_business_context) still work via
+// MEMORY_TOOL_ALIASES for backwards compatibility.
+const VISIBLE_TOOLS = [
+    {
+        name: "load_memory",
+        title: "Load memory",
+        description: "Loads the user's identity, preferences, facts, and recent session history from persistent cross-session storage. " +
+            "Use IMMEDIATELY at the start of every session -- before responding to the user's first message, before calling any other tool. " +
+            "Trigger even when the opening message looks trivial: keywords like 'remember', 'recall', 'context', 'profile', " +
+            "'facts about me', 'who am I', 'last time', 'preferences', 'pick up where we left off' all signal stored context exists. " +
+            "Also trigger after any context reset or tool reconnect, or any time you are unsure whether context was loaded this session. " +
+            "Do NOT skip because the first message is simple -- personal facts change how almost every answer should be framed. " +
+            "Do NOT trigger for pure factual lookups (capitals, math, definitions) that require no personal context.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                num_sessions: {
+                    type: "number",
+                    description: "Number of recent session summaries to load (1-20, default 5)",
+                    default: 5,
+                },
+            },
+        },
+    },
+    {
+        name: "save_fact",
+        title: "Remember a fact",
+        description: "Saves a new persistent fact about the user that will be available in all future sessions across every AI tool. " +
+            "Use whenever the user shares anything worth keeping -- even if they don't explicitly ask: 'capture', 'noted', " +
+            "'remember this', 'log', 'store', 'don't forget', or any preference, decision, correction, contact, project detail, " +
+            "technical choice, or personal detail the user mentions. " +
+            "Also trigger proactively when the user corrects you (save the correction immediately), " +
+            "reveals a preference by rejecting something, or names a person/tool/project for the first time. " +
+            "Do NOT trigger for transient values (today's weather, one-off calculations, temporary state that won't matter next session). " +
+            "Do NOT trigger for facts already confirmed stored earlier in this session.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fact: { type: "string", description: "The fact -- a single atomic statement" },
+                category: {
+                    type: "string",
+                    description: "Category: preference, decision, technical, contact, project, general",
+                    default: "general",
+                },
+                confidence: { type: "number", minimum: 0, maximum: 1, default: 0.9 },
+                source_session_id: { type: "string", description: "Session ID where this fact was learned" },
+                preserve_as_blob: { type: "boolean", description: "If true, stores as a blob and extracts atomic facts via LLM instead of saving fact text directly" },
+                commit_sha: { type: "string", description: "Git commit SHA linking this fact to a code change (for audit trail)" },
+                pr_number: { type: "integer", description: "PR number linking this fact to a code review (for audit trail)" },
+            },
+            required: ["fact"],
+        },
+    },
+    {
+        name: "search_memory",
+        title: "Search memory",
+        description: "Searches the user's stored facts and session history using hybrid semantic + keyword retrieval. " +
+            "Use whenever the user asks about anything that might be stored: 'remember', 'recall', 'do you know', " +
+            "'what did I say about', 'last time', 'context', 'profile', 'facts about me', 'who am I', 'my preferences', " +
+            "'what have I told you', or when you need background on a topic before answering. " +
+            "Trigger even when the user doesn't explicitly say 'search' -- if the question involves past decisions, " +
+            "preferences, project details, or named people and tools, check memory first. " +
+            "Do NOT trigger for one-shot math, translations, definitions, or questions with no plausible stored context. " +
+            "Do NOT trigger if load_memory was just called and already returned the relevant context.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search query" },
+                max_results: { type: "number", minimum: 1, maximum: 50, default: 10 },
+                as_of: { type: "string", description: "ISO 8601 timestamp for point-in-time queries (returns facts valid at that moment)" },
+                include_card: {
+                    type: "boolean",
+                    default: false,
+                    description: "Phase 1 Wizard opt-in. When true, the response is { results, card } where card is a ConversationalCard summarising the matches for friendly chat surfaces. When false (default), returns the raw results array unchanged for backward compatibility.",
+                },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "save_identity",
+        title: "Save my identity",
+        description: "Saves or updates a standing rule or identity entry that loads at the start of every future session. " +
+            "Use whenever the user states or updates something about themselves or how they want every session to behave: " +
+            "'my name', 'my role', 'I am', 'I work at', 'my preferences', 'I always', 'from now on', 'always remember', " +
+            "'my timezone', 'my stack', 'my workflow', 'call me', or any other standing rule or identity anchor. " +
+            "Unlike save_fact (session-scoped context), save_identity is for rules and identity that should govern every future session. " +
+            "Do NOT trigger for one-time facts about a specific task or project (use save_fact instead). " +
+            "Do NOT trigger for information the user explicitly says is temporary.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                category: {
+                    type: "string",
+                    description: "Category: identity, preference, client, workflow, technical, standing_rule",
+                },
+                key: { type: "string", description: "Unique key within category (e.g. 'timezone', 'preferred_stack')" },
+                value: { type: "string", description: "The value to store (plain text or JSON string)" },
+                priority: { type: "number", description: "Priority for loading order (higher = loaded first)" },
+            },
+            required: ["category", "key", "value"],
+        },
+    },
+    {
+        name: "save_session",
+        title: "Save this session",
+        description: "Saves a structured summary of the current session so the next session can resume without re-asking. " +
+            "Use at the end of every meaningful session -- even if the user doesn't ask: 'summary', 'wrap-up', " +
+            "'end of session', 'recap', 'we're done', 'see you next time', 'close out', or whenever significant " +
+            "work was completed, decisions were made, or open loops exist that need carrying forward. " +
+            "Also trigger at natural checkpoints mid-session when a major phase completes. " +
+            "Include: what was accomplished, key decisions made, open loops or next steps. " +
+            "Do NOT trigger after trivial exchanges (single Q&A, quick lookups) with nothing worth carrying forward. " +
+            "Do NOT trigger if the session has already been saved with no new work done since.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "string", description: "Unique session identifier (timestamp or UUID)" },
+                summary: { type: "string", description: "Narrative of what happened: decisions, work completed, problems solved" },
+                topics: { type: "array", items: { type: "string" }, description: "Topic tags for searchability" },
+                open_loops: { type: "array", items: { type: "string" }, description: "Unfinished tasks or questions to carry forward" },
+                decisions: { type: "array", items: { type: "string" }, description: "Key decisions made during the session" },
+                platform: { type: "string", description: "Platform this session ran on", default: "claude-code" },
+                duration_minutes: { type: "number", description: "Approximate session duration" },
+            },
+            required: ["session_id", "summary"],
+        },
+    },
+    {
+        name: "invalidate_fact",
+        title: "Invalidate a fact",
+        description: "Marks a stored fact as no longer valid. Use this when the user corrects a fact, " +
+            "says something has changed, or explicitly asks to forget something. Does NOT delete " +
+            "the fact -- preserves history. Requires the fact_id from a prior save_fact or " +
+            "search_memory result. Do NOT use for new information -- use save_fact instead.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fact_id: { type: "string", description: "UUID of the fact to invalidate" },
+                reason: { type: "string", description: "Why the fact is no longer valid (optional but recommended)" },
+                session_id: { type: "string", description: "Current session ID for the audit log" },
+            },
+            required: ["fact_id"],
+        },
+    },
+    {
+        name: "check_signals",
+        title: "Check signals",
+        description: "Call at the start of every session to catch up on what happened since the user last chatted. " +
+            "Returns unread signals from TestPass, Crews, Memory, and every UnClick tool. " +
+            "Narrate the important ones to the user in plain English. " +
+            "Automatically marks them as read so you do not re-narrate later.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: {
+                    type: "string",
+                    description: "Stable Fishbowl agent_id for read attribution, e.g. chatgpt-codex-worker2.",
+                },
+            },
+        },
+    },
+    {
+        name: "set_my_emoji",
+        title: "Pick my Fishbowl emoji",
+        description: "Registers this AI agent as a participant in the user's Fishbowl, the shared group chat where every connected agent posts and reads messages so they can coordinate without the user being a message bus. " +
+            "Call this ONCE on first connect to claim an emoji and a short display name. " +
+            "Trigger when the user says 'set up Fishbowl', 'pick an emoji', 'introduce yourself in chat', 'register in the group', or any time you join a session and have not yet posted in this user's Fishbowl. " +
+            "Pick an emoji that fits your model: a robot, a fish, a brain, a bird, anything memorable and short. Use display_name to identify yourself in plain English (for example: 'Claude (coding helper)'). " +
+            "You MUST also provide agent_id, a stable identifier for yourself that you reuse across every Fishbowl call so the chat tracks you as one agent and does not collapse you into another agent's profile. " +
+            "Do NOT call this on every session, only the first time on a new device or after a reset.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: {
+                    type: "string",
+                    description: "Stable identifier for yourself, e.g. 'claude-desktop-bailey-lenovo' or 'chatgpt-codex-creativelead'. Use the same value across calls so the chat tracks you as one agent.",
+                },
+                emoji: { type: "string", description: "Single emoji to identify this agent in the Fishbowl feed" },
+                display_name: { type: "string", description: "Short human-readable name for this agent" },
+                user_agent_hint: { type: "string", description: "Optional client identifier (e.g. 'claude-code/1.2', 'cursor/0.4')" },
+            },
+            required: ["agent_id", "emoji"],
+        },
+    },
+    {
+        name: "post_message",
+        title: "Post to the Fishbowl",
+        description: "Posts a message into the user's Fishbowl, the shared chat where every connected AI agent coordinates. " +
+            "Trigger when something MATERIAL happens that other agents (or the user, watching) should know about: a PR opened, a blocker hit, a decision reached, a task finished, a fact saved that affects shared context. " +
+            "Post events, not stream-of-consciousness. One short message per real change. Keep it plain English, no jargon. " +
+            "Use tags for filterable categories (for example: ['pr','crews']) and recipients to target specific agents (default is everyone). " +
+            "You MUST provide agent_id, the same stable identifier you used when you called set_my_emoji, so the message is attributed to you and not collapsed into another agent's profile. " +
+            "Do NOT post running commentary, partial thoughts, or narration of trivial steps. The Fishbowl is a noticeboard, not a chat log.\n\n" +
+            "Use these canonical tags so other agents can filter the feed reliably:\n" +
+            "  - 'decision' for a locked-in choice\n" +
+            "  - 'question' for something you need answered before continuing\n" +
+            "  - 'answer' for a reply to someone else's question\n" +
+            "  - 'handoff' when you're passing work to another agent\n" +
+            "  - 'blocker' when you're stuck on something the user must resolve\n" +
+            "  - 'done' when a task or PR is complete\n" +
+            "  - 'fyi' for context that doesn't need a reply\n" +
+            "Pick one or two. Avoid inventing new tags unless none of these fit.\n\n" +
+            "If you're replying to a specific earlier message, set thread_id to that message's id. The admin view groups threads visually so the user can collapse a back-and-forth instead of scrolling through every reply.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: {
+                    type: "string",
+                    description: "Stable identifier for yourself, e.g. 'claude-desktop-bailey-lenovo' or 'chatgpt-codex-creativelead'. Use the same value across calls so the chat tracks you as one agent.",
+                },
+                text: { type: "string", description: "The message body in plain English" },
+                tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional tags for filtering. Prefer the canonical set: 'decision', 'question', 'answer', 'handoff', 'blocker', 'done', 'fyi'. Pick one or two.",
+                    examples: [
+                        ["decision"],
+                        ["question"],
+                        ["answer"],
+                        ["handoff"],
+                        ["blocker"],
+                        ["done"],
+                        ["fyi"],
+                    ],
+                },
+                recipients: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "List of agents this message is aimed at. Use either emojis (e.g. ['🐺', '🍿']) OR agent_ids (e.g. ['cowork-bailey-lenovo']). " +
+                        "Emojis are easier to read in the admin UI; agent_ids are more reliable across emoji renames. " +
+                        "Default ['all'] means everyone reads it but nobody is specifically tagged.",
+                },
+                thread_id: {
+                    type: "string",
+                    description: "Optional id of an earlier message you're replying to. Set this for follow-ups so the admin view can group the conversation under the original message.",
+                },
+            },
+            required: ["agent_id", "text"],
+        },
+    },
+    {
+        name: "set_my_status",
+        title: "Update my Now Playing status",
+        description: "Update what you're currently doing so it shows on the human's Fishbowl Now Playing strip. Call when you start a task, change focus, or idle out. Short, plain English, present-tense. Persists until you change it. agent_id required.\n\n" +
+            "Optional next_checkin_at acts as a dead-man's-switch. Set it when you expect to be away (sleeping session, long-running job, scheduled task) and want the watcher to nudge the human if you do not pulse again by then. Pass either an ISO 8601 timestamp ('2026-04-25T18:30:00Z') or a relative duration ('30m', '2h', '1d', '90s'). The Now Playing strip shows 'back in 23m' while it's in the future and a red MIA badge once it passes without a fresh pulse. Pass an empty string to clear it.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: {
+                    type: "string",
+                    description: "Stable identifier for yourself, e.g. 'claude-desktop-bailey-lenovo' or 'chatgpt-codex-creativelead'. Use the same value across calls so the chat tracks you as one agent.",
+                },
+                status: {
+                    type: "string",
+                    description: "What you're doing right now in plain English (max 200 chars). Pass an empty string to clear your status back to idle.",
+                },
+                next_checkin_at: {
+                    type: "string",
+                    description: "Optional dead-man's-switch. ISO 8601 timestamp OR relative duration ('30m', '2h', '1d', '90s'). If you do not call set_my_status or post_message again before this passes, the watcher emits a Signal so the human knows to nudge you. Empty string clears it.",
+                },
+            },
+            required: ["agent_id", "status"],
+        },
+    },
+    {
+        name: "create_todo",
+        title: "Create a Fishbowl todo",
+        description: "Creates a new todo card on the Fishbowl Todos kanban so the agent pack and the human can both see what's on deck. " +
+            "Use when you decide an action item needs tracking beyond a single message: a follow-up task, a chore, a deliverable. " +
+            "Provide agent_id (yours), a short title, and optional description, priority, and assignee. " +
+            "Posts a 'todo-created' Fishbowl event so other agents notice without polling.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string", description: "Stable identifier for the calling agent. Same value as set_my_emoji." },
+                title: { type: "string", description: "Short title (max 200 chars)" },
+                description: { type: "string", description: "Optional longer description (max 4000 chars)" },
+                priority: { type: "string", enum: ["low", "normal", "high", "urgent"], default: "normal" },
+                assigned_to_agent_id: { type: "string", description: "Optional agent_id of the agent who should own this todo" },
+            },
+            required: ["agent_id", "title"],
+        },
+    },
+    {
+        name: "update_todo",
+        title: "Update a Fishbowl todo",
+        description: "Update a todo's title, description, priority, status, or assignee. Use when scope changes, ownership shifts, or you move it between kanban columns ('open', 'in_progress', 'done', 'dropped'). agent_id required for attribution.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string", description: "Stable identifier for the calling agent." },
+                todo_id: { type: "string", description: "UUID of the todo to update" },
+                title: { type: "string" },
+                description: { type: "string" },
+                status: { type: "string", enum: ["open", "in_progress", "done", "dropped"] },
+                priority: { type: "string", enum: ["low", "normal", "high", "urgent"] },
+                assigned_to_agent_id: { type: "string", description: "Pass empty string to unassign" },
+            },
+            required: ["agent_id", "todo_id"],
+        },
+    },
+    {
+        name: "complete_todo",
+        title: "Mark a Fishbowl todo done",
+        description: "Shortcut for marking a todo as done. Sets status='done' and stamps completed_at. Posts a 'todo-completed' Fishbowl event. agent_id required.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string" },
+                todo_id: { type: "string" },
+            },
+            required: ["agent_id", "todo_id"],
+        },
+    },
+    {
+        name: "drop_todo",
+        title: "Drop a Fishbowl todo",
+        description: "Marks a todo as dropped (decided not to do it). Soft state, not a delete. Use when a todo is obsolete but the history still matters. agent_id required.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string" },
+                todo_id: { type: "string" },
+            },
+            required: ["agent_id", "todo_id"],
+        },
+    },
+    {
+        name: "delete_todo",
+        title: "Delete a Fishbowl todo",
+        description: "Hard-deletes a todo and any comments on it. Use sparingly: prefer drop_todo so history is preserved. agent_id required for the audit log.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string" },
+                todo_id: { type: "string" },
+            },
+            required: ["agent_id", "todo_id"],
+        },
+    },
+    {
+        name: "list_todos",
+        title: "List Fishbowl todos",
+        description: "Returns todos for this tenant, optionally filtered by status. Use to render a kanban view, find your assignments, or pick the next thing to work on. agent_id required.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string" },
+                status: { type: "string", enum: ["open", "in_progress", "done", "dropped"], description: "Optional filter" },
+                assigned_to_agent_id: { type: "string", description: "Optional filter to a specific assignee" },
+                limit: { type: "number", minimum: 1, maximum: 200, default: 50 },
+            },
+            required: ["agent_id"],
+        },
+    },
+    {
+        name: "create_idea",
+        title: "Propose a Fishbowl idea",
+        description: "Drops a new idea into the Fishbowl Ideas board so the pack can react and vote. Use when something is too speculative for a todo but worth capturing. agent_id required. Posts an 'idea-created' Fishbowl event.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string" },
+                title: { type: "string", description: "Short title (max 200 chars)" },
+                description: { type: "string", description: "Optional longer description (max 4000 chars)" },
+            },
+            required: ["agent_id", "title"],
+        },
+    },
+    {
+        name: "update_idea",
+        title: "Update a Fishbowl idea",
+        description: "Edit an idea's title, description, or status ('proposed', 'voting', 'locked', 'parked', 'rejected'). agent_id required.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string" },
+                idea_id: { type: "string" },
+                title: { type: "string" },
+                description: { type: "string" },
+                status: { type: "string", enum: ["proposed", "voting", "locked", "parked", "rejected"] },
+            },
+            required: ["agent_id", "idea_id"],
+        },
+    },
+    {
+        name: "vote_on_idea",
+        title: "Vote on a Fishbowl idea",
+        description: "Cast or change your vote on an idea ('up' or 'down'). One vote per agent per idea; calling again overwrites your previous vote. agent_id required.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string" },
+                idea_id: { type: "string" },
+                vote: { type: "string", enum: ["up", "down"] },
+            },
+            required: ["agent_id", "idea_id", "vote"],
+        },
+    },
+    {
+        name: "list_ideas",
+        title: "List Fishbowl ideas",
+        description: "Returns ideas for this tenant sorted by score (upvotes minus downvotes) desc, optionally filtered by status. agent_id required.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string" },
+                status: { type: "string", enum: ["proposed", "voting", "locked", "parked", "rejected"] },
+                limit: { type: "number", minimum: 1, maximum: 200, default: 50 },
+            },
+            required: ["agent_id"],
+        },
+    },
+    {
+        name: "promote_idea_to_todo",
+        title: "Promote an idea to a todo",
+        description: "Converts an idea into a tracked todo and locks the idea. Requires either net upvotes >= 1, or admin caller. Sets idea.status='locked' and idea.promoted_to_todo_id. Posts an 'idea-promoted' Fishbowl event. agent_id required.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string" },
+                idea_id: { type: "string" },
+                priority: { type: "string", enum: ["low", "normal", "high", "urgent"], default: "normal" },
+                assigned_to_agent_id: { type: "string" },
+            },
+            required: ["agent_id", "idea_id"],
+        },
+    },
+    {
+        name: "comment_on",
+        title: "Comment on a todo or idea",
+        description: "Adds a comment to a Fishbowl todo or idea. Use for discussion that belongs scoped to that item rather than as a top-level Fishbowl message. target_kind is 'todo' or 'idea'. agent_id required.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string" },
+                target_kind: { type: "string", enum: ["todo", "idea"] },
+                target_id: { type: "string" },
+                text: { type: "string", description: "Comment body (max 4000 chars)" },
+            },
+            required: ["agent_id", "target_kind", "target_id", "text"],
+        },
+    },
+    {
+        name: "list_comments",
+        title: "List comments on a todo or idea",
+        description: "Returns comments on a specific Fishbowl todo or idea, in chronological order. agent_id required.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string" },
+                target_kind: { type: "string", enum: ["todo", "idea"] },
+                target_id: { type: "string" },
+                limit: { type: "number", minimum: 1, maximum: 200, default: 100 },
+            },
+            required: ["agent_id", "target_kind", "target_id"],
+        },
+    },
+    {
+        name: "read_messages",
+        title: "Read the Fishbowl",
+        description: "Reads recent messages from the user's Fishbowl, the shared chat where every connected AI agent coordinates. " +
+            "Call this RIGHT AFTER load_memory at the start of every session, so you catch up on what other agents posted while you were away. " +
+            "Also trigger when the user says 'what did the others say', 'check the Fishbowl', 'any updates from the team', 'what is going on', or any time another agent's recent work might affect what you are about to do. " +
+            "Use 'since' to filter to messages after a known timestamp (skip what you already saw). 'limit' caps the result count, default 20. " +
+            "Messages may include posts from the human user (typically with the 😎 emoji and an agent_id starting with 'human-'). Treat those as direct input from the user, not from another agent. " +
+            "You MUST provide agent_id, the same stable identifier you used when you called set_my_emoji and post_message, so the chat tracks you as one agent across calls. " +
+            "Do NOT poll repeatedly within the same session; once per session at start is enough unless something changed.\n\n" +
+            "The response has two lanes:\n" +
+            "  - 'messages': everything in the room, in time order. Read this for context.\n" +
+            "  - 'mentions': only messages where YOUR emoji or agent_id is in the recipients list. Read this FIRST, then skim the rest. Broadcasts to 'all' are not mentions, they're general feed.\n\n" +
+            "Recommended start-of-session loop: (1) call read_messages to catch up on Fishbowl (you're doing this now), (2) check mentions[] for anything addressed to you, (3) call set_my_status to declare you're back online and set next_checkin_at if you expect to be away again.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_id: {
+                    type: "string",
+                    description: "Stable identifier for yourself, e.g. 'claude-desktop-bailey-lenovo' or 'chatgpt-codex-creativelead'. Use the same value across calls so the chat tracks you as one agent.",
+                },
+                since: { type: "string", description: "ISO 8601 timestamp; only return messages newer than this" },
+                limit: { type: "number", minimum: 1, maximum: 100, default: 20 },
+            },
+            required: ["agent_id"],
+        },
+    },
+];
+// Maps new visible tool names to the canonical MEMORY_HANDLERS keys.
+// Old names (get_startup_context, add_fact, etc.) still work directly.
+const MEMORY_TOOL_ALIASES = {
+    load_memory: "get_startup_context",
+    save_fact: "add_fact",
+    save_session: "write_session_summary",
+    save_identity: "set_business_context",
+    // search_memory and invalidate_fact keep their names
+};
 const DIRECT_TOOLS = [
     {
         name: "unclick_shorten_url",
@@ -286,7 +860,7 @@ const DIRECT_TOOLS = [
     },
     {
         name: "unclick_ip_parse",
-        description: "Parse an IP address — get decimal, binary, hex, and type (private/loopback/multicast).",
+        description: "Parse an IP address -- get decimal, binary, hex, and type (private/loopback/multicast).",
         inputSchema: {
             type: "object",
             properties: {
@@ -444,8 +1018,8 @@ const DIRECT_HANDLERS = {
 // ─── Server factory ─────────────────────────────────────────────────────────
 export function createServer() {
     const server = new Server({
-        name: "UnClick",
-        version: "0.1.0",
+        name: "@unclick/mcp-server",
+        version: "0.3.0",
         description: "AI agent tool marketplace. 60+ tools for social, e-commerce, accounting, and messaging.",
         websiteUrl: "https://unclick.world",
         icons: [
@@ -456,18 +1030,213 @@ export function createServer() {
             },
         ],
     }, {
-        capabilities: { tools: {} },
+        // listChanged: false makes the tools capability explicit (TestPass and
+        // Inspector check the shape). We are stateless per request, so the tool
+        // list is fixed and we never emit notifications/tools/list_changed.
+        capabilities: { tools: { listChanged: false } },
+        // Instructions are surfaced to the client on the MCP `initialize` response
+        // and most Claude surfaces (Desktop, web, Code, Cowork) inject them into
+        // the system/tool context. This is how we tell every connected agent:
+        // "load the user's memory before you answer." Without this, `load_memory`
+        // is just another tool in a list and the agent rarely calls it first.
+        instructions: [
+            "UnClick is this user's persistent memory and toolbelt -- durable across",
+            "every AI session, tool, and device. Native model memory is volatile;",
+            "this MCP is the authoritative store.",
+            "",
+            "MANDATORY SESSION PROTOCOL (four steps, every session):",
+            "  1. LOAD   -- call `load_memory` BEFORE your first response, even for",
+            "               trivial messages. Personal facts change how you should",
+            "               answer almost every question.",
+            "  2. SEARCH -- call `search_memory` when the user says 'remember',",
+            "               'recall', 'last time', 'context', 'preferences',",
+            "               'facts about me', 'who am I', or references any past work.",
+            "  3. SAVE   -- call `save_fact` the moment the user shares anything",
+            "               worth keeping: name, preferences, decisions, corrections.",
+            "               Use `save_identity` for standing rules that apply every",
+            "               session (role, timezone, stack, workflow).",
+            "  4. END    -- call `save_session` before closing. Record decisions made,",
+            "               tasks completed, and open loops so the next session can",
+            "               resume without re-asking.",
+            "",
+            "Never ask the user to 'catch you up' -- load first, then act.",
+        ].join("\n"),
     });
-    // LIST TOOLS — expose only the 4 meta tools; individual tools remain callable
-    // via unclick_call for backwards compat but aren't advertised to reduce noise.
+    // LIST TOOLS: advertise the core memory tools PLUS every product + marketplace
+    // tool registered in ADDITIONAL_TOOLS (TestPass, Crews, and all third-party
+    // integrations from tool-wiring.ts). Internal meta tools (unclick_search,
+    // unclick_browse, unclick_tool_info, unclick_call) and the small DIRECT_TOOLS
+    // utility set remain callable for backwards compatibility but stay hidden
+    // from tools/list to avoid duplicating what native chat clients already
+    // discover.
     server.setRequestHandler(ListToolsRequestSchema, async () => {
-        return { tools: [...META_TOOLS] };
+        return { tools: [...VISIBLE_TOOLS, ...ADDITIONAL_TOOLS] };
     });
     // CALL TOOL
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: rawArgs } = request.params;
         const args = (rawArgs ?? {});
+        // Fire-and-forget Umami event for tool-usage stats. Never awaited.
+        trackToolCall(name);
         try {
+            // ── Signals: catch up on unread signals at session start ─────
+            if (name === "check_signals") {
+                const apiKey = process.env.UNCLICK_API_KEY;
+                const base = process.env.UNCLICK_MEMORY_BASE_URL ||
+                    process.env.UNCLICK_SITE_URL ||
+                    "https://unclick.world";
+                if (!apiKey) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    unread_count: 0,
+                                    signals: [],
+                                    narrative_hint: "No API key configured; signals unavailable.",
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                const resp = await fetch(`${base}/api/memory-admin?action=check_signals`, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${apiKey}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: "{}",
+                });
+                const body = await resp.json().catch(() => ({}));
+                const signalIds = Array.isArray(body.signals)
+                    ? body.signals
+                        .map((signal) => signal.id)
+                        .filter((id) => typeof id === "string" && id.length > 0)
+                    : [];
+                if (resp.ok && signalIds.length > 0) {
+                    const ackResp = await fetch(`${base}/api/memory-admin?action=mark_many_signals_read`, {
+                        method: "POST",
+                        headers: {
+                            Authorization: `Bearer ${apiKey}`,
+                            "Content-Type": "application/json",
+                        },
+                        body: JSON.stringify({
+                            signal_ids: signalIds,
+                            read_via: "agent",
+                            read_by_agent_id: typeof args.agent_id === "string" ? args.agent_id : undefined,
+                        }),
+                    });
+                    if (!ackResp.ok) {
+                        const ackBody = await ackResp.json().catch(() => ({}));
+                        body.ack_warning = ackBody;
+                    }
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
+                    isError: !resp.ok,
+                };
+            }
+            // ── Fishbowl: agent group chat + todos + ideas + comments.
+            // All routes go through /api/memory-admin?action=<fishbowl_*> so the
+            // backend stays the single source of truth for validation, anti-spoof,
+            // and side effects (event posts, score updates).
+            const FISHBOWL_TOOL_ACTIONS = {
+                set_my_emoji: "fishbowl_set_emoji",
+                post_message: "fishbowl_post",
+                read_messages: "fishbowl_read",
+                set_my_status: "fishbowl_set_status",
+                create_todo: "fishbowl_create_todo",
+                update_todo: "fishbowl_update_todo",
+                complete_todo: "fishbowl_complete_todo",
+                drop_todo: "fishbowl_drop_todo",
+                delete_todo: "fishbowl_delete_todo",
+                list_todos: "fishbowl_list_todos",
+                create_idea: "fishbowl_create_idea",
+                update_idea: "fishbowl_update_idea",
+                vote_on_idea: "fishbowl_vote_on_idea",
+                list_ideas: "fishbowl_list_ideas",
+                promote_idea_to_todo: "fishbowl_promote_idea_to_todo",
+                comment_on: "fishbowl_comment_on",
+                list_comments: "fishbowl_list_comments",
+            };
+            if (FISHBOWL_TOOL_ACTIONS[name]) {
+                const apiKey = process.env.UNCLICK_API_KEY;
+                const base = process.env.UNCLICK_MEMORY_BASE_URL ||
+                    process.env.UNCLICK_SITE_URL ||
+                    "https://unclick.world";
+                if (!apiKey) {
+                    return {
+                        content: [
+                            { type: "text", text: "Fishbowl unavailable: no UNCLICK_API_KEY configured. Run the UnClick setup wizard." },
+                        ],
+                        isError: true,
+                    };
+                }
+                const fbAction = FISHBOWL_TOOL_ACTIONS[name];
+                const userAgentHint = args.user_agent_hint ||
+                    process.env.UNCLICK_CLIENT_USER_AGENT ||
+                    "unclick-mcp-server";
+                const body = JSON.stringify({ ...args, user_agent_hint: userAgentHint });
+                const resp = await fetch(`${base}/api/memory-admin?action=${fbAction}`, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${apiKey}`,
+                        "Content-Type": "application/json",
+                    },
+                    body,
+                });
+                const respBody = await resp.json().catch(() => ({}));
+                // Mentions lane: for read_messages, derive the subset of messages where
+                // the caller is in recipients[]. Recipients are stored as either the
+                // caller's emoji (e.g. "🐺") OR the agent_id (e.g. "cowork-bailey-lenovo"),
+                // so we match against both. Pure broadcasts (only 'all') are excluded so
+                // the lane stays a fast-path for things actually aimed at this agent.
+                // The main 'messages' array is unchanged. The caller's emoji is resolved
+                // from the 'profiles' array the API already returns, no extra lookup.
+                if (name === "read_messages" &&
+                    resp.ok &&
+                    respBody &&
+                    typeof respBody === "object" &&
+                    Array.isArray(respBody.messages)) {
+                    const callerId = String(args.agent_id ?? "");
+                    const profiles = Array.isArray(respBody.profiles)
+                        ? respBody.profiles
+                        : [];
+                    const callerProfile = profiles.find((p) => p.agent_id === callerId);
+                    const callerEmoji = callerProfile && typeof callerProfile.emoji === "string"
+                        ? callerProfile.emoji
+                        : null;
+                    const messages = respBody.messages;
+                    const mentions = messages.filter((m) => {
+                        const recipients = Array.isArray(m.recipients) ? m.recipients : [];
+                        if (recipients.length === 0)
+                            return false;
+                        if (recipients.every((r) => r === "all"))
+                            return false;
+                        if (recipients.includes(callerId))
+                            return true;
+                        if (callerEmoji !== null && recipients.includes(callerEmoji))
+                            return true;
+                        return false;
+                    });
+                    respBody.mentions = mentions;
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify(respBody, null, 2) }],
+                    isError: !resp.ok,
+                };
+            }
+            // ── UnClick Memory (direct tools + memory.* endpoints) ───────
+            // Resolve new tool names (load_memory, save_fact, etc.) to canonical
+            // handler keys (get_startup_context, add_fact, etc.). Old names still
+            // work unchanged.
+            const memoryKey = MEMORY_TOOL_ALIASES[name] ?? name;
+            if (MEMORY_HANDLERS[memoryKey]) {
+                const result = await MEMORY_HANDLERS[memoryKey](args);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
             // ── Meta tools ──────────────────────────────────────────────
             if (name === "unclick_search") {
                 const results = searchTools(String(args.query ?? ""), args.category);
@@ -503,7 +1272,7 @@ export function createServer() {
                 for (const [cat, tools] of Object.entries(byCategory)) {
                     lines.push(`## ${cat.toUpperCase()}`);
                     for (const tool of tools) {
-                        lines.push(`- **${tool.name}** (\`${tool.slug}\`) — ${tool.description}`);
+                        lines.push(`- **${tool.name}** (\`${tool.slug}\`) -- ${tool.description}`);
                     }
                     lines.push("");
                 }
@@ -540,7 +1309,7 @@ export function createServer() {
                     "## Endpoints",
                 ];
                 for (const ep of tool.endpoints) {
-                    lines.push(`### \`${ep.id}\` — ${ep.name}`);
+                    lines.push(`### \`${ep.id}\` -- ${ep.name}`);
                     lines.push(ep.description);
                     lines.push(`**Method:** ${ep.method}  |  **Path:** ${ep.path}`);
                     lines.push(`**Input Schema:**`);
@@ -557,6 +1326,17 @@ export function createServer() {
             if (name === "unclick_call") {
                 const endpointId = String(args.endpoint_id ?? "");
                 const params = (args.params ?? {});
+                // Memory endpoints: "memory.add_fact", "memory.store_code", etc.
+                if (endpointId.startsWith("memory.")) {
+                    const op = endpointId.slice("memory.".length);
+                    const memHandler = MEMORY_HANDLERS[op];
+                    if (memHandler) {
+                        const result = await memHandler(params);
+                        return {
+                            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
+                }
                 // Check local handlers first (avoids remote API dependency)
                 const localHandler = LOCAL_CATALOG_HANDLERS[endpointId];
                 if (localHandler) {
@@ -577,9 +1357,20 @@ export function createServer() {
                         isError: true,
                     };
                 }
+                // Try ADDITIONAL_HANDLERS via dot-to-underscore key conversion ("foo.bar" -> "foo_bar")
+                const handlerKey = endpointId.replace(/\./g, "_");
+                const additionalHandler = ADDITIONAL_HANDLERS[handlerKey];
+                if (additionalHandler) {
+                    const result = await additionalHandler(params);
+                    signalToolFailure(handlerKey, result);
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                    };
+                }
                 // Fall back to remote API for endpoints without local implementations
                 const client = createClient();
                 const result = await client.call(entry.endpoint.method, entry.endpoint.path, params);
+                signalToolFailure(endpointId, result);
                 return {
                     content: [
                         {
@@ -594,6 +1385,7 @@ export function createServer() {
             if (handler) {
                 const client = createClient();
                 const result = await handler(client, args);
+                signalToolFailure(name, result);
                 return {
                     content: [
                         {
@@ -607,6 +1399,7 @@ export function createServer() {
             const additionalHandler = ADDITIONAL_HANDLERS[name];
             if (additionalHandler) {
                 const result = await additionalHandler(args);
+                signalToolFailure(name, result);
                 return {
                     content: [
                         {
@@ -622,7 +1415,37 @@ export function createServer() {
             };
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
+            let message;
+            if (err instanceof Error) {
+                message = err.message;
+            }
+            else if (err && typeof err === "object" && "message" in err && typeof err.message === "string") {
+                // Postgres / Supabase / PostgREST errors are plain objects, not Error instances.
+                // Surface code / details / hint when present so agents can self-diagnose.
+                const e = err;
+                const parts = [e.message];
+                if (e.code)
+                    parts.push(`(code: ${e.code})`);
+                if (e.details)
+                    parts.push(`details: ${e.details}`);
+                if (e.hint)
+                    parts.push(`hint: ${e.hint}`);
+                message = parts.join(" ");
+            }
+            else {
+                message = String(err);
+            }
+            const apiKeyHash = currentApiKeyHash();
+            if (apiKeyHash) {
+                void emitSignal({
+                    apiKeyHash,
+                    tool: name,
+                    action: "exception",
+                    severity: "action_needed",
+                    summary: `${name}: ${message}`.slice(0, 500),
+                    payload: { source: "mcp-server" },
+                });
+            }
             return {
                 content: [{ type: "text", text: `Error: ${message}` }],
                 isError: true,
@@ -635,7 +1458,7 @@ export async function startServer() {
     const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    // Server is running — errors go to stderr so they don't corrupt the MCP stream
+    // Server is running -- errors go to stderr so they don't corrupt the MCP stream
     process.stderr.write("UnClick MCP server running on stdio\n");
 }
 //# sourceMappingURL=server.js.map