@kynver-app/mcp-agent-os 0.2.0 → 0.2.2

package/README.md

@@ -30,6 +30,10 @@ Schemas are mirrored in `lib/mcp/tool-manifests/kynver-mcp-agent-os.json` in
 the Kynver repo (used as the static fallback when stdio spawn isn't available
 — e.g. on Vercel).
 
+Memory write/update tools accept `sourceRefs` for structured provenance. Use it
+to attach repo paths, commits, PRs, map files, sessions, tools, or URLs to
+important memories instead of burying those pointers in freeform text.
+
 ## Env
 
 | Var | Purpose |

package/dist/server.d.ts

@@ -2,12 +2,9 @@
  * Kynver Agentic OS MCP server: slug-keyed agent identity, goals, projects,
  * sessions, contacts, and long-term memory.
  *
- * Each tool proxies to `/api/agent-os/{slug}/*` on Kynver — those routes are
- * admin-only. The `slug` argument is optional on every tool; if omitted, it
- * falls back to `KYNVER_AGENT_OS_SLUG` env, then to `"ghost"`. This is the
- * twelve-tool `agent_os_*` family — previously colocated with `kynver-mcp-analyst`,
- * split into its own package so each AgentOS deployment can mount this server
- * independently from the analyst surface.
+ * Each tool proxies to `/api/agent-os/{slug}/*` on Kynver. The optional `slug`
+ * argument resolves in order: explicit arg → `KYNVER_AGENT_OS_SLUG` → cached
+ * `GET /api/agent-os` `{ primarySlug }` → list first item → legacy `"ghost"`.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare function createAgentOsServer(): McpServer;

package/dist/server.js

@@ -2,49 +2,88 @@
  * Kynver Agentic OS MCP server: slug-keyed agent identity, goals, projects,
  * sessions, contacts, and long-term memory.
  *
- * Each tool proxies to `/api/agent-os/{slug}/*` on Kynver — those routes are
- * admin-only. The `slug` argument is optional on every tool; if omitted, it
- * falls back to `KYNVER_AGENT_OS_SLUG` env, then to `"ghost"`. This is the
- * twelve-tool `agent_os_*` family — previously colocated with `kynver-mcp-analyst`,
- * split into its own package so each AgentOS deployment can mount this server
- * independently from the analyst surface.
+ * Each tool proxies to `/api/agent-os/{slug}/*` on Kynver. The optional `slug`
+ * argument resolves in order: explicit arg → `KYNVER_AGENT_OS_SLUG` → cached
+ * `GET /api/agent-os` `{ primarySlug }` → list first item → legacy `"ghost"`.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { get, post, patch } from "./lib/kynver-client.js";
-function toolResult(text) {
-    return { content: [{ type: "text", text }] };
-}
 function jsonResult(data) {
-    return toolResult(JSON.stringify(data, null, 2));
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        structuredContent: data,
+    };
 }
+const MCP_LEGACY_SLUG_FALLBACK = "ghost";
 export function createAgentOsServer() {
-    const server = new McpServer({ name: "kynver-mcp-agent-os", version: "0.1.0" }, { capabilities: { tools: {} } });
-    // The deprecated `server.tool(name, desc, zodShape, handler)` overloads
-    // generate a heavy generic type graph that OOMs tsc when many tools share
-    // one file. We use `registerTool` with an `as any` cast — same pattern the
-    // estimator/contents packages already use — so the build stays fast.
+    const server = new McpServer({ name: "kynver-mcp-agent-os", version: "0.2.2" }, { capabilities: { tools: {} } });
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     function register(name, description, inputSchema, cb) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         server.registerTool(name, { description, inputSchema }, cb);
     }
-    // ─── Agentic OS Tools ──────────────────────────────────────────────
-    // Proxy to /api/agent-os/{slug}/* (admin-only on Kynver). Each tool takes
-    // an optional `slug` (the AgentOS slug — Ghost, Aria, etc.); if omitted it
-    // falls back to KYNVER_AGENT_OS_SLUG, then "ghost". The Ghost-scoped
-    // `agent_os_*` aliases and the legacy `agentOS_*` set were unified into
-    // this single snake_case family.
-    const defaultAgentOsSlug = () => process.env.KYNVER_AGENT_OS_SLUG?.trim() || "ghost";
-    const osSlug = (s) => (s && s.trim()) || defaultAgentOsSlug();
-    register("agent_os_get_context", "Get the agent's full Agentic-OS state in one call: identity, open goals, active projects with current focus/next-actions/blockers, recent sessions, contacts, and long-term memory stats. Use at session start instead of reading SOUL.md / USER.md / MEMORY.md.", { slug: z.string().optional().describe("AgentOS slug. Defaults to KYNVER_AGENT_OS_SLUG, then 'ghost'.") }, async (args) => jsonResult(await get(`/agent-os/${osSlug(args.slug)}/stats`)));
+    let cachedResolvedPrimarySlug = null;
+    async function resolveToolSlug(explicitSlug) {
+        const trimmed = explicitSlug?.trim();
+        if (trimmed)
+            return trimmed;
+        const fromEnv = process.env.KYNVER_AGENT_OS_SLUG?.trim();
+        if (fromEnv)
+            return fromEnv;
+        if (cachedResolvedPrimarySlug)
+            return cachedResolvedPrimarySlug;
+        try {
+            const body = await get("/agent-os");
+            const primary = typeof body.primarySlug === "string" ? body.primarySlug.trim() : "";
+            if (primary) {
+                cachedResolvedPrimarySlug = primary;
+                return primary;
+            }
+            const first = Array.isArray(body.items) ? body.items[0]?.slug : undefined;
+            if (typeof first === "string") {
+                const t = first.trim();
+                if (t) {
+                    cachedResolvedPrimarySlug = t;
+                    return t;
+                }
+            }
+        }
+        catch {
+            // fall through
+        }
+        return MCP_LEGACY_SLUG_FALLBACK;
+    }
+    const slugField = z.string().optional().describe("AgentOS slug within your account. Omit to use env or server-discovered primary (GET /api/agent-os). Legacy: `ghost`.");
+    const sourceRefSchema = z
+        .object({
+        type: z
+            .enum(["repo", "commit", "branch", "pr", "map", "session", "tool", "url", "manual", "unknown"])
+            .describe("What kind of source backs this memory."),
+        label: z.string().optional(),
+        repo: z.string().optional(),
+        path: z.string().optional(),
+        commit: z.string().optional(),
+        branch: z.string().optional(),
+        pr: z.union([z.number(), z.string()]).optional(),
+        url: z.string().optional(),
+        sessionId: z.string().optional(),
+        toolName: z.string().optional(),
+        note: z.string().optional(),
+    })
+        .passthrough();
+    register("agent_os_get_context", "Get the agent's full Agentic-OS state in one call: identity, open goals, active projects with current focus/next-actions/blockers, recent sessions, contacts, and long-term memory stats. Use at session start instead of reading SOUL.md / USER.md / MEMORY.md.", { slug: slugField }, async (args) => {
+        const s = await resolveToolSlug(args.slug);
+        return jsonResult(await get(`/agent-os/${s}/stats`));
+    });
     register("agent_os_open_session", "Call this at the START of every session. Records channel, model, and opens a session record for continuity. Ghost calls this immediately after agent_os_get_context on startup.", {
         channel: z.string().describe("Runtime channel: 'webchat' | 'telegram' | 'discord' | …"),
         model: z.string().optional().describe("Model used for the session (default 'claude-sonnet-4-6')."),
-        slug: z.string().optional().describe("AgentOS slug. Defaults to KYNVER_AGENT_OS_SLUG, then 'ghost'."),
+        slug: slugField,
     }, async (args) => {
         const { slug, ...body } = args;
-        return jsonResult(await post(`/agent-os/${osSlug(slug)}/sessions`, body));
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await post(`/agent-os/${s}/sessions`, body));
     });
     register("agent_os_close_session", "Call this at the END of every session with a summary of what was accomplished and key decisions made. This is how Ghost maintains cross-session continuity — without it, the next session has no record of what happened.", {
         sessionId: z.string(),
@@ -53,17 +92,18 @@ export function createAgentOsServer() {
         decisionsLog: z.unknown().optional(),
         goalIds: z.array(z.string()).optional(),
         projectIds: z.array(z.string()).optional(),
-        slug: z.string().optional(),
+        slug: slugField,
     }, async (args) => {
         const { slug, sessionId, ...body } = args;
-        return jsonResult(await patch(`/agent-os/${osSlug(slug)}/sessions/${sessionId}`, body));
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await patch(`/agent-os/${s}/sessions/${sessionId}`, body));
     });
     register("agent_os_log_session", "Append a structured session-log entry to the agent's daily log. Call at session end or mid-session checkpoints. Replaces writing to memory/YYYY-MM-DD.md. Entries accumulate across sessions; consolidation distils them into long-term memory.", {
         summary: z.string().describe("2-4 sentence summary of what was worked on."),
         topicsWorked: z.array(z.string()).optional().describe("Topics covered this session."),
         keyDecisions: z.array(z.string()).optional().describe("Important decisions made."),
         date: z.string().optional().describe("Date to log against (YYYY-MM-DD, defaults to today UTC)."),
-        slug: z.string().optional().describe("AgentOS slug. Defaults to KYNVER_AGENT_OS_SLUG, then 'ghost'."),
+        slug: slugField,
     }, async (args) => {
         const lines = [args.summary];
         if (args.topicsWorked?.length)
@@ -73,7 +113,8 @@ export function createAgentOsServer() {
             args.keyDecisions.forEach((d) => lines.push(`- ${d}`));
         }
         const entry = lines.join("\n");
-        return jsonResult(await post(`/agent-os/${osSlug(args.slug)}/daily-log`, {
+        const s = await resolveToolSlug(args.slug);
+        return jsonResult(await post(`/agent-os/${s}/daily-log`, {
             entry,
             ...(args.date ? { date: args.date } : {}),
         }));
@@ -84,7 +125,7 @@ export function createAgentOsServer() {
             .optional()
             .describe("Filter by status. Omit to get all goals."),
         projectId: z.string().optional().describe("Filter by project DB ID."),
-        slug: z.string().optional(),
+        slug: slugField,
     }, async (args) => {
         const params = new URLSearchParams();
         if (args.status)
@@ -92,7 +133,8 @@ export function createAgentOsServer() {
         if (args.projectId)
             params.set("projectId", args.projectId);
         const qs = params.toString();
-        return jsonResult(await get(`/agent-os/${osSlug(args.slug)}/goals${qs ? `?${qs}` : ""}`));
+        const s = await resolveToolSlug(args.slug);
+        return jsonResult(await get(`/agent-os/${s}/goals${qs ? `?${qs}` : ""}`));
     });
     register("agent_os_update_goal", "Create a new goal or update an existing one. Pass goalId to update; omit to create (title is then required). Set status=complete with an outcome to close a goal (stamps closedAt). projectId is the project DB ID from agent_os_get_projects.", {
         title: z.string().optional().describe("Goal title. Required when creating."),
@@ -103,29 +145,31 @@ export function createAgentOsServer() {
         analystHypothesisId: z.string().optional().describe("Optional analyst hypothesis to link (create-only)."),
         outcome: z.string().optional().describe("Outcome — include when closing a goal."),
         goalId: z.string().optional().describe("ID of existing goal to update. Omit to create."),
-        slug: z.string().optional(),
+        slug: slugField,
     }, async (args) => {
         const { goalId, slug, ...body } = args;
+        const s = await resolveToolSlug(slug);
         if (goalId) {
-            return jsonResult(await patch(`/agent-os/${osSlug(slug)}/goals/${goalId}`, body));
+            return jsonResult(await patch(`/agent-os/${s}/goals/${goalId}`, body));
         }
         if (!body.title) {
             return jsonResult({ error: "title is required when creating a goal" });
         }
-        return jsonResult(await post(`/agent-os/${osSlug(slug)}/goals`, body));
+        return jsonResult(await post(`/agent-os/${s}/goals`, body));
     });
     register("agent_os_get_projects", "Get all projects the agent is tracking with current focus, next actions, blockers, and status. Replaces reading project sections of MEMORY.md.", {
         status: z
             .enum(["active", "on_hold", "shipped", "archived"])
             .optional()
             .describe("Filter by project status. Omit to get all."),
-        slug: z.string().optional(),
+        slug: slugField,
     }, async (args) => {
         const params = new URLSearchParams();
         if (args.status)
             params.set("status", args.status);
         const qs = params.toString();
-        return jsonResult(await get(`/agent-os/${osSlug(args.slug)}/projects${qs ? `?${qs}` : ""}`));
+        const s = await resolveToolSlug(args.slug);
+        return jsonResult(await get(`/agent-os/${s}/projects${qs ? `?${qs}` : ""}`));
     });
     register("agent_os_update_project", "Update a project's current focus, next-actions queue, blockers list, status, or repo/deploy URLs. The projectId is the DB ID from agent_os_get_projects.", {
         projectId: z.string().describe("Project DB ID (from agent_os_get_projects)."),
@@ -137,20 +181,22 @@ export function createAgentOsServer() {
         blockers: z.array(z.string()).optional().describe("Current blockers."),
         repoUrl: z.string().optional(),
         deployUrl: z.string().optional(),
-        slug: z.string().optional(),
+        slug: slugField,
     }, async (args) => {
         const { projectId, slug, ...body } = args;
-        return jsonResult(await patch(`/agent-os/${osSlug(slug)}/projects/${projectId}`, body));
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await patch(`/agent-os/${s}/projects/${projectId}`, body));
     });
     register("agent_os_search_memory", "Semantic + keyword hybrid search over the agent's long-term MARM memory (ownerType=agent). Use to recall specific decisions, project details, or lessons without loading full context. Replaces grep/reading MEMORY.md. Results include rrfScore — a Reciprocal Rank Fusion score where ~0.033 is a near-perfect match. Higher is better; do not treat low numbers as poor results.", {
         query: z.string().describe("Natural language query to search memory."),
         k: z.number().optional().describe("Number of results (default 10, max 50)."),
-        slug: z.string().optional(),
+        slug: slugField,
     }, async (args) => {
         const params = new URLSearchParams({ q: args.query });
         if (args.k)
             params.set("k", String(args.k));
-        return jsonResult(await get(`/agent-os/${osSlug(args.slug)}/memory?${params}`));
+        const s = await resolveToolSlug(args.slug);
+        return jsonResult(await get(`/agent-os/${s}/memory?${params}`));
     });
     register("agent_os_write_memory", "Write a durable memory entry to the agent's MARM. Use to persist decisions, lessons, or key facts across sessions. Replaces appending to MEMORY.md. Either pass a category enum (mapped to sourceId) or override sourceId directly.", {
         content: z.string().describe("The memory content to store."),
@@ -161,7 +207,8 @@ export function createAgentOsServer() {
             .describe("Memory category. Mapped to sourceId: long_term/contact/tool_config -> 'agent:long-term', project -> 'agent:project'. Ignored if sourceId is set."),
         sourceId: z.string().optional().describe("Advanced: override the sourceId tag directly. If set, category is ignored."),
         metadata: z.record(z.string(), z.unknown()).optional(),
-        slug: z.string().optional().describe("AgentOS slug. Defaults to KYNVER_AGENT_OS_SLUG, then 'ghost'."),
+        sourceRefs: z.array(sourceRefSchema).optional().describe("Structured provenance references for this memory, such as repo/path/commit/PR/map/session."),
+        slug: slugField,
     }, async (args) => {
         const categoryToSourceId = {
             long_term: "agent:long-term",
@@ -177,10 +224,19 @@ export function createAgentOsServer() {
             body.sourceId = sourceId;
         if (args.metadata)
             body.metadata = args.metadata;
-        return jsonResult(await post(`/agent-os/${osSlug(args.slug)}/memory`, body));
+        if (args.sourceRefs)
+            body.sourceRefs = args.sourceRefs;
+        const s = await resolveToolSlug(args.slug);
+        return jsonResult(await post(`/agent-os/${s}/memory`, body));
+    });
+    register("agent_os_get_contacts", "Get all people the agent knows: their relationship, context, preferences, and notes. Replaces reading USER.md and contact sections of MEMORY.md.", { slug: slugField }, async (args) => {
+        const s = await resolveToolSlug(args.slug);
+        return jsonResult(await get(`/agent-os/${s}/contacts`));
+    });
+    register("agent_os_consolidate_memory", "Trigger a memory consolidation pass: LLM reviews recent daily logs and distils key decisions, lessons, and facts into long-term MARM memory. Use during heartbeat maintenance instead of manually rewriting MEMORY.md. Rate-limited to 2 runs per agent per day.", { slug: slugField }, async (args) => {
+        const s = await resolveToolSlug(args.slug);
+        return jsonResult(await post(`/agent-os/${s}/consolidate`, {}));
     });
-    register("agent_os_get_contacts", "Get all people the agent knows: their relationship, context, preferences, and notes. Replaces reading USER.md and contact sections of MEMORY.md.", { slug: z.string().optional() }, async (args) => jsonResult(await get(`/agent-os/${osSlug(args.slug)}/contacts`)));
-    register("agent_os_consolidate_memory", "Trigger a memory consolidation pass: LLM reviews recent daily logs and distils key decisions, lessons, and facts into long-term MARM memory. Use during heartbeat maintenance instead of manually rewriting MEMORY.md. Rate-limited to 2 runs per agent per day.", { slug: z.string().optional() }, async (args) => jsonResult(await post(`/agent-os/${osSlug(args.slug)}/consolidate`, {})));
     register("agent_os_create_project", "Create a new project in the agent OS. Use this to add a newly started project to tracking. Returns the created project with its DB id.", {
         name: z.string().describe("Project name (required)."),
         description: z.string().optional(),
@@ -190,10 +246,11 @@ export function createAgentOsServer() {
         blockers: z.array(z.string()).optional(),
         repoUrl: z.string().optional(),
         deployUrl: z.string().optional(),
-        slug: z.string().optional(),
+        slug: slugField,
     }, async (args) => {
         const { slug, ...body } = args;
-        return jsonResult(await post(`/agent-os/${osSlug(slug)}/projects`, body));
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await post(`/agent-os/${s}/projects`, body));
     });
     register("agent_os_create_contact", "Add a new contact (or upsert by name) to the agent OS. Use when you meet someone new or want to record info about a person.", {
         name: z.string().describe("Contact name (required)."),
@@ -201,10 +258,11 @@ export function createAgentOsServer() {
         context: z.string().optional().describe("Background on who they are and what they do."),
         preferences: z.record(z.string(), z.unknown()).optional().describe("Communication preferences, timezone, style notes, etc."),
         notes: z.string().optional(),
-        slug: z.string().optional(),
+        slug: slugField,
     }, async (args) => {
         const { slug, ...body } = args;
-        return jsonResult(await post(`/agent-os/${osSlug(slug)}/contacts`, body));
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await post(`/agent-os/${s}/contacts`, body));
     });
     register("agent_os_update_contact", "Update an existing contact by their DB id. Use agent_os_get_contacts to get the id first.", {
         contactId: z.string().describe("DB id of the contact to update (from agent_os_get_contacts)."),
@@ -213,25 +271,30 @@ export function createAgentOsServer() {
         context: z.string().optional(),
         preferences: z.record(z.string(), z.unknown()).optional(),
         notes: z.string().optional(),
-        slug: z.string().optional(),
+        slug: slugField,
     }, async (args) => {
         const { contactId, slug, ...body } = args;
-        return jsonResult(await patch(`/agent-os/${osSlug(slug)}/contacts/${contactId}`, body));
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await patch(`/agent-os/${s}/contacts/${contactId}`, body));
     });
     register("agent_os_update_memory", "Update an existing memory entry by its key/slug. Use to correct or replace a previously written memory. The key must match the slug used when the memory was written — if key was omitted on write, the auto-generated slug (note-<timestamp>) is returned in the write response.", {
         key: z.string().describe("The slug/key of the memory to update (from the original agent_os_write_memory call)."),
         content: z.string().describe("New content to replace the existing memory with."),
         sourceId: z.string().optional().describe("Override the sourceId tag if needed."),
         metadata: z.record(z.string(), z.unknown()).optional(),
-        slug: z.string().optional().describe("AgentOS slug. Defaults to KYNVER_AGENT_OS_SLUG, then ghost."),
+        sourceRefs: z.array(sourceRefSchema).optional().describe("Structured provenance references for this replacement memory."),
+        slug: slugField,
     }, async (args) => {
-        const { key, slug, content, sourceId, metadata } = args;
+        const { key, slug, content, sourceId, metadata, sourceRefs } = args;
         const body = { content, slug: key };
         if (sourceId)
             body.sourceId = sourceId;
         if (metadata)
             body.metadata = metadata;
-        return jsonResult(await post(`/agent-os/${osSlug(slug)}/memory`, body));
+        if (sourceRefs)
+            body.sourceRefs = sourceRefs;
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await post(`/agent-os/${s}/memory`, body));
     });
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kynver-app/mcp-agent-os",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Kynver Agentic OS MCP server — slug-keyed agent identity, goals, projects, sessions, and long-term memory",
   "type": "module",
   "bin": {