@kynver-app/mcp-agent-os 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# @kynver-app/mcp-agent-os
+
+Kynver Agentic OS MCP server. Exposes the 12-tool `agent_os_*` family that
+proxies to `/api/agent-os/{slug}/*` on a Kynver deployment. Each tool accepts
+an optional `slug` argument; if omitted, it falls back to
+`KYNVER_AGENT_OS_SLUG` env, then to `"ghost"`.
+
+This is the **external surface only**. The in-app Kynver agent does not
+dispatch these tools — they exist for MCP clients (Claude Code, Cursor,
+OpenClaw, etc.) that connect to a running Kynver deployment.
+
+## Tools
+
+The full family:
+
+- `agent_os_get_context`
+- `agent_os_open_session`
+- `agent_os_close_session`
+- `agent_os_log_session`
+- `agent_os_list_goals`
+- `agent_os_update_goal`
+- `agent_os_get_projects`
+- `agent_os_update_project`
+- `agent_os_search_memory`
+- `agent_os_write_memory`
+- `agent_os_get_contacts`
+- `agent_os_consolidate_memory`
+
+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).
+
+## Env
+
+| Var | Purpose |
+|---|---|
+| `KYNVER_API_URL` | Kynver origin, e.g. `https://kynver.com` |
+| `KYNVER_API_KEY` | Bearer token for external authentication |
+| `KYNVER_AGENT_OS_SLUG` | Default agent slug when the tool's `slug` arg is omitted (defaults to `"ghost"`) |
+| `KYNVER_SERVICE_SECRET` | Required when running under SSE and forwarding internal `userId` headers |
+| `PORT` | SSE port (defaults to `3101`) |
+
+## OpenClaw / Claude Code config
+
+Once this package is published, the Ghost workspace's MCP config needs **two
+separate** Kynver MCP server entries — one for the analyst surface and one for
+this Agentic-OS surface:
+
+```jsonc
+{
+  "mcpServers": {
+    "kynver-analyst": {
+      "command": "npx",
+      "args": ["-y", "@kynver-app/mcp-analyst"],
+      "env": {
+        "KYNVER_API_URL": "https://kynver.com",
+        "KYNVER_API_KEY": "${KYNVER_API_KEY}"
+      }
+    },
+    "kynver-agent-os": {
+      "command": "npx",
+      "args": ["-y", "@kynver-app/mcp-agent-os"],
+      "env": {
+        "KYNVER_API_URL": "https://kynver.com",
+        "KYNVER_API_KEY": "${KYNVER_API_KEY}",
+        "KYNVER_AGENT_OS_SLUG": "ghost"
+      }
+    }
+  }
+}
+```
+
+The split mirrors the server-side change of 2026-05-14: the `agent_os_*`
+family was extracted from `@kynver-app/mcp-analyst` into this dedicated
+package so each AgentOS deployment can mount it independently from the
+analyst tools.

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Kynver Agentic OS MCP server — stdio entry point.
+ * Run: node dist/index.js
+ * Env: KYNVER_API_URL, KYNVER_API_KEY (required)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Kynver Agentic OS MCP server — stdio entry point.
+ * Run: node dist/index.js
+ * Env: KYNVER_API_URL, KYNVER_API_KEY (required)
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createAgentOsServer } from "./server.js";
+const server = createAgentOsServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/lib/kynver-client.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Thin fetch wrapper for Kynver API. Base URL from KYNVER_API_URL; optional Bearer from KYNVER_API_KEY.
+ *
+ * Supports per-request user identity via AsyncLocalStorage. When a userId is
+ * set in the request context (e.g. from the SSE route), all API calls include
+ * X-Kynver-User-Id and X-Kynver-Service-Secret headers so the Kynver API
+ * executes operations on behalf of the correct user.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+interface RequestContext {
+    userId?: string;
+}
+export declare const requestContext: AsyncLocalStorage<RequestContext>;
+export declare function get<T = unknown>(path: string): Promise<T>;
+export declare function post<T = unknown>(path: string, body: unknown): Promise<T>;
+export declare function patch<T = unknown>(path: string, body: unknown): Promise<T>;
+export declare function put<T = unknown>(path: string, body: unknown): Promise<T>;
+export declare function del<T = unknown>(path: string): Promise<T>;
+export declare function hasApiKey(): boolean;
+export declare function noApiKeyMessage(): string;
+export {};

package/dist/lib/kynver-client.js

@@ -0,0 +1,146 @@
+/**
+ * Thin fetch wrapper for Kynver API. Base URL from KYNVER_API_URL; optional Bearer from KYNVER_API_KEY.
+ *
+ * Supports per-request user identity via AsyncLocalStorage. When a userId is
+ * set in the request context (e.g. from the SSE route), all API calls include
+ * X-Kynver-User-Id and X-Kynver-Service-Secret headers so the Kynver API
+ * executes operations on behalf of the correct user.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+export const requestContext = new AsyncLocalStorage();
+const DEFAULT_FETCH_TIMEOUT_MS = 120_000;
+const MAX_ERROR_MESSAGE_LEN = 2_000;
+// ---------------------------------------------------------------------------
+// Config (read per call so late-loaded env in tests / dotenv works)
+// ---------------------------------------------------------------------------
+function getBaseUrl() {
+    const u = process.env.KYNVER_API_URL?.trim();
+    if (u)
+        return u.replace(/\/$/, "");
+    if (process.env.NODE_ENV === "development") {
+        return "http://localhost:3000";
+    }
+    throw new Error("KYNVER_API_URL is not set. Set it to your Kynver app origin (e.g. https://kynver.com or http://localhost:3000).");
+}
+function getApiKey() {
+    return process.env.KYNVER_API_KEY?.trim() ?? "";
+}
+function assertSafeApiPath(path) {
+    const p = path.startsWith("/") ? path : `/${path}`;
+    if (p.includes("..") || p.includes("\0")) {
+        throw new Error("Invalid API path: path traversal is not allowed");
+    }
+}
+function url(path) {
+    assertSafeApiPath(path);
+    const p = path.startsWith("/") ? path : `/${path}`;
+    const apiPath = p.startsWith("/api") ? p : `/api${p}`;
+    return `${getBaseUrl()}${apiPath}`;
+}
+function getHeaders() {
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    const apiKey = getApiKey();
+    if (apiKey) {
+        headers["Authorization"] = `Bearer ${apiKey}`;
+    }
+    const ctx = requestContext.getStore();
+    const userId = ctx?.userId;
+    const serviceSecret = process.env.KYNVER_SERVICE_SECRET;
+    if (userId) {
+        if (!serviceSecret) {
+            throw new Error("X-Kynver-User-Id was set in context but KYNVER_SERVICE_SECRET is missing; refusing to send an unscoped request.");
+        }
+        headers["X-Kynver-User-Id"] = userId;
+        headers["X-Kynver-Service-Secret"] = serviceSecret;
+    }
+    return headers;
+}
+// ---------------------------------------------------------------------------
+// Response handling
+// ---------------------------------------------------------------------------
+function normalizeErrorMessage(msg) {
+    const s = String(msg).replace(/\s+/g, " ").trim();
+    return s.length > MAX_ERROR_MESSAGE_LEN ? `${s.slice(0, MAX_ERROR_MESSAGE_LEN)}…` : s;
+}
+async function handleResponse(res) {
+    const text = await res.text();
+    if (!res.ok) {
+        let msg = text;
+        try {
+            const j = JSON.parse(text);
+            msg = j.error ?? j.message ?? text;
+        }
+        catch {
+            // use text as-is
+        }
+        throw new Error(normalizeErrorMessage(msg || `HTTP ${res.status}`));
+    }
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+async function fetchWithTimeout(path, init) {
+    const timeoutMs = Number(process.env.KYNVER_FETCH_TIMEOUT_MS ?? DEFAULT_FETCH_TIMEOUT_MS);
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url(path), { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+// ---------------------------------------------------------------------------
+// HTTP methods
+// ---------------------------------------------------------------------------
+export async function get(path) {
+    const res = await fetchWithTimeout(path, {
+        method: "GET",
+        headers: getHeaders(),
+    });
+    return handleResponse(res);
+}
+export async function post(path, body) {
+    const res = await fetchWithTimeout(path, {
+        method: "POST",
+        headers: getHeaders(),
+        body: JSON.stringify(body),
+    });
+    return handleResponse(res);
+}
+export async function patch(path, body) {
+    const res = await fetchWithTimeout(path, {
+        method: "PATCH",
+        headers: getHeaders(),
+        body: JSON.stringify(body),
+    });
+    return handleResponse(res);
+}
+export async function put(path, body) {
+    const res = await fetchWithTimeout(path, {
+        method: "PUT",
+        headers: getHeaders(),
+        body: JSON.stringify(body),
+    });
+    return handleResponse(res);
+}
+export async function del(path) {
+    const res = await fetchWithTimeout(path, {
+        method: "DELETE",
+        headers: getHeaders(),
+    });
+    return handleResponse(res);
+}
+export function hasApiKey() {
+    return !!getApiKey();
+}
+export function noApiKeyMessage() {
+    return "No API key configured. Set KYNVER_API_KEY in your MCP server config.";
+}

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createAgentOsServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,185 @@
+/**
+ * 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.
+ */
+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));
+}
+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.
+    // 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`)));
+    register("agent_os_open_session", "Mark the start of a session. Returns the session id — pass it to agent_os_close_session at the end.", {
+        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'."),
+    }, async (args) => {
+        const { slug, ...body } = args;
+        return jsonResult(await post(`/agent-os/${osSlug(slug)}/sessions`, body));
+    });
+    register("agent_os_close_session", "Close a session with an end-of-session summary (2-3 sentences), the topics worked on, and optional decisions log / touched goal & project ids. The summary is ingested into long-term memory.", {
+        sessionId: z.string(),
+        summary: z.string(),
+        topicsWorked: z.array(z.string()).optional(),
+        decisionsLog: z.unknown().optional(),
+        goalIds: z.array(z.string()).optional(),
+        projectIds: z.array(z.string()).optional(),
+        slug: z.string().optional(),
+    }, async (args) => {
+        const { slug, sessionId, ...body } = args;
+        return jsonResult(await patch(`/agent-os/${osSlug(slug)}/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'."),
+    }, async (args) => {
+        const lines = [args.summary];
+        if (args.topicsWorked?.length)
+            lines.push(`Topics: ${args.topicsWorked.join(", ")}`);
+        if (args.keyDecisions?.length) {
+            lines.push("Key decisions:");
+            args.keyDecisions.forEach((d) => lines.push(`- ${d}`));
+        }
+        const entry = lines.join("\n");
+        return jsonResult(await post(`/agent-os/${osSlug(args.slug)}/daily-log`, {
+            entry,
+            ...(args.date ? { date: args.date } : {}),
+        }));
+    });
+    register("agent_os_list_goals", "List the agent's goals, optionally filtered by status or project. Replaces reading the pending sections of MEMORY.md.", {
+        status: z
+            .enum(["open", "in_progress", "blocked", "complete", "cancelled"])
+            .optional()
+            .describe("Filter by status. Omit to get all goals."),
+        projectId: z.string().optional().describe("Filter by project DB ID."),
+        slug: z.string().optional(),
+    }, async (args) => {
+        const params = new URLSearchParams();
+        if (args.status)
+            params.set("status", args.status);
+        if (args.projectId)
+            params.set("projectId", args.projectId);
+        const qs = params.toString();
+        return jsonResult(await get(`/agent-os/${osSlug(args.slug)}/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."),
+        description: z.string().optional(),
+        status: z.enum(["open", "in_progress", "blocked", "complete", "cancelled"]).optional(),
+        priority: z.enum(["low", "normal", "high", "critical"]).optional(),
+        projectId: z.string().optional().describe("Project DB ID to associate."),
+        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(),
+    }, async (args) => {
+        const { goalId, slug, ...body } = args;
+        if (goalId) {
+            return jsonResult(await patch(`/agent-os/${osSlug(slug)}/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));
+    });
+    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(),
+    }, 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}` : ""}`));
+    });
+    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)."),
+        name: z.string().optional(),
+        description: z.string().optional(),
+        status: z.enum(["active", "on_hold", "shipped", "archived"]).optional(),
+        currentFocus: z.string().optional().describe("What's being worked on right now."),
+        nextActions: z.array(z.string()).optional().describe("Ordered list of next steps."),
+        blockers: z.array(z.string()).optional().describe("Current blockers."),
+        repoUrl: z.string().optional(),
+        deployUrl: z.string().optional(),
+        slug: z.string().optional(),
+    }, async (args) => {
+        const { projectId, slug, ...body } = args;
+        return jsonResult(await patch(`/agent-os/${osSlug(slug)}/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.", {
+        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(),
+    }, 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}`));
+    });
+    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."),
+        key: z.string().optional().describe("Unique slug identifier for this memory (e.g. 'kynver-arch-decision-2026-05'). Defaults to a timestamped note slug."),
+        category: z
+            .enum(["long_term", "project", "contact", "tool_config"])
+            .optional()
+            .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'."),
+    }, async (args) => {
+        const categoryToSourceId = {
+            long_term: "agent:long-term",
+            project: "agent:project",
+            contact: "agent:long-term",
+            tool_config: "agent:long-term",
+        };
+        const sourceId = args.sourceId ?? (args.category ? categoryToSourceId[args.category] : undefined);
+        const body = { content: args.content };
+        if (args.key)
+            body.slug = args.key;
+        if (sourceId)
+            body.sourceId = sourceId;
+        if (args.metadata)
+            body.metadata = args.metadata;
+        return jsonResult(await post(`/agent-os/${osSlug(args.slug)}/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: 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`, {})));
+    return server;
+}

package/dist/sse.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SSE entry point for the Agentic OS MCP server.
+ *
+ * Supports two authentication modes:
+ *   1. Internal (Kynver dashboard): userId + KYNVER_SERVICE_SECRET query params
+ *   2. External (Claude Code, Cursor, any MCP client): Kynver API key via
+ *      query param (?apiKey=…) or Authorization header
+ *
+ * External keys are validated by calling GET /api/users/me on the Kynver API.
+ * Once authenticated, tool calls execute on behalf of the resolved user via
+ * the requestContext AsyncLocalStorage.
+ */
+export {};

package/dist/sse.js

@@ -0,0 +1,130 @@
+/**
+ * SSE entry point for the Agentic OS MCP server.
+ *
+ * Supports two authentication modes:
+ *   1. Internal (Kynver dashboard): userId + KYNVER_SERVICE_SECRET query params
+ *   2. External (Claude Code, Cursor, any MCP client): Kynver API key via
+ *      query param (?apiKey=…) or Authorization header
+ *
+ * External keys are validated by calling GET /api/users/me on the Kynver API.
+ * Once authenticated, tool calls execute on behalf of the resolved user via
+ * the requestContext AsyncLocalStorage.
+ */
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { createServer } from "node:http";
+import { createAgentOsServer } from "./server.js";
+import { requestContext } from "./lib/kynver-client.js";
+const PORT = parseInt(process.env.PORT ?? "3101", 10);
+const BASE_URL = process.env.KYNVER_API_URL ?? "https://kynver.com";
+const SERVICE_SECRET = process.env.KYNVER_SERVICE_SECRET ?? "";
+// ---------------------------------------------------------------------------
+// Session tracking — maps sessionId → { transport, userId }
+// ---------------------------------------------------------------------------
+const sessions = {};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Validate an external API key by calling the Kynver API. */
+async function resolveUser(apiKey) {
+    try {
+        const res = await fetch(`${BASE_URL}/api/users/me`, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read and JSON-parse the request body (needed for raw http.Server). */
+function parseBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => {
+            try {
+                resolve(JSON.parse(Buffer.concat(chunks).toString()));
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+        req.on("error", reject);
+    });
+}
+function parseUrl(req) {
+    return new URL(req.url ?? "/", `http://localhost:${PORT}`);
+}
+// ---------------------------------------------------------------------------
+// HTTP server
+// ---------------------------------------------------------------------------
+const httpServer = createServer(async (req, res) => {
+    const url = parseUrl(req);
+    const path = url.pathname;
+    // ── SSE connection ──────────────────────────────────────────────────
+    if (req.method === "GET" && path === "/sse") {
+        // Internal auth: Kynver dashboard passes userId + service secret
+        const internalUserId = url.searchParams.get("userId");
+        const internalSecret = url.searchParams.get("secret");
+        // External auth: API key via query param or Authorization header
+        const apiKey = url.searchParams.get("apiKey") ??
+            req.headers.authorization?.replace("Bearer ", "") ??
+            "";
+        let userId = null;
+        if (internalUserId && SERVICE_SECRET && internalSecret === SERVICE_SECRET) {
+            userId = internalUserId;
+        }
+        else if (apiKey) {
+            userId = await resolveUser(apiKey);
+        }
+        if (!userId) {
+            res.writeHead(401, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                error: "Unauthorized. Provide a valid Kynver API key.",
+            }));
+            return;
+        }
+        console.log(`[MCP SSE] New connection (userId: ${userId})`);
+        const transport = new SSEServerTransport("/messages", res);
+        sessions[transport.sessionId] = { transport, userId };
+        res.on("close", () => {
+            console.log(`[MCP SSE] Connection closed: ${transport.sessionId}`);
+            delete sessions[transport.sessionId];
+        });
+        const server = createAgentOsServer();
+        await server.connect(transport);
+        return;
+    }
+    // ── Message handler (client → server JSON-RPC messages) ─────────────
+    if (req.method === "POST" && path === "/messages") {
+        const sessionId = url.searchParams.get("sessionId");
+        const entry = sessionId ? sessions[sessionId] : undefined;
+        if (!entry) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                error: "No active SSE session for this sessionId",
+            }));
+            return;
+        }
+        const body = await parseBody(req);
+        // Wrap in request context so kynver-client sends the right user headers
+        await requestContext.run({ userId: entry.userId }, async () => {
+            await entry.transport.handlePostMessage(req, res, body);
+        });
+        return;
+    }
+    // ── Health check ────────────────────────────────────────────────────
+    if (req.method === "GET" && path === "/health") {
+        res.writeHead(200, { "Content-Type": "text/plain" });
+        res.end("ok");
+        return;
+    }
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Not found" }));
+});
+httpServer.listen(PORT, () => {
+    console.log(`[MCP SSE] Agentic OS server listening on port ${PORT}`);
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@kynver-app/mcp-agent-os",
+  "version": "0.1.0",
+  "description": "Kynver Agentic OS MCP server — slug-keyed agent identity, goals, projects, sessions, and long-term memory",
+  "type": "module",
+  "bin": {
+    "kynver-mcp-agent-os": "dist/index.js"
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "node --max-old-space-size=8192 ../../node_modules/typescript/bin/tsc",
+    "dev": "node --max-old-space-size=8192 ../../node_modules/typescript/bin/tsc --watch",
+    "start": "node dist/index.js",
+    "start:sse": "node dist/sse.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.0.0"
+  }
+}