@kynver-app/mcp-agent-os 0.3.18 → 0.3.19

package/dist/lib/mcp-sse-server.d.ts

@@ -0,0 +1,29 @@
+import { type IncomingMessage } from "node:http";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const MAX_SSE_BODY_BYTES: number;
+export type SessionAuth = {
+    kind: "apiKey";
+    apiKey: string;
+} | {
+    kind: "internal";
+    userId: string;
+};
+type RequestContextStore = {
+    run: <T>(store: {
+        userId?: string;
+    }, fn: () => Promise<T>) => Promise<T>;
+};
+export type StartKynverMcpSseServerOptions = {
+    label: string;
+    defaultPort: number;
+    createMcpServer: () => McpServer | Promise<McpServer>;
+    requestContext: RequestContextStore;
+};
+export declare function headerValue(req: IncomingMessage, name: string): string | null;
+export declare function timingSafeEqualString(a: string, b: string): boolean;
+export declare function hasForbiddenQueryAuth(url: URL): boolean;
+export declare function resolveListenHost(): string;
+export declare function parseJsonBody(req: IncomingMessage, maxBytes?: number): Promise<unknown>;
+export declare function validateMcporterServerName(name: string): string;
+export declare function startKynverMcpSseServer(options: StartKynverMcpSseServerOptions): void;
+export {};

package/dist/lib/mcp-sse-server.js

@@ -0,0 +1,191 @@
+// @generated — synced from packages/kynver-mcp-sse-lib/src/index.ts via scripts/sync-mcp-sse-server.mjs
+// Do not edit by hand; change the canonical file and re-run the sync script.
+import { createServer } from "node:http";
+import { timingSafeEqual } from "node:crypto";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+export const MAX_SSE_BODY_BYTES = 1 * 1024 * 1024;
+const FORBIDDEN_QUERY_KEYS = ["secret", "userId"];
+export function headerValue(req, name) {
+    const v = req.headers[name];
+    return typeof v === "string" ? v : Array.isArray(v) ? (v[0] ?? null) : null;
+}
+export function timingSafeEqualString(a, b) {
+    const left = Buffer.from(a);
+    const right = Buffer.from(b);
+    if (left.length !== right.length)
+        return false;
+    return timingSafeEqual(left, right);
+}
+export function hasForbiddenQueryAuth(url) {
+    return FORBIDDEN_QUERY_KEYS.some((key) => url.searchParams.has(key));
+}
+function queryApiKey(url) {
+    return url.searchParams.get("apiKey")?.trim() ?? "";
+}
+export function resolveListenHost() {
+    const configured = process.env.MCP_SSE_HOST?.trim();
+    return configured || "127.0.0.1";
+}
+export function parseJsonBody(req, maxBytes = MAX_SSE_BODY_BYTES) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let totalSize = 0;
+        req.on("data", (chunk) => {
+            totalSize += chunk.length;
+            if (totalSize > maxBytes) {
+                req.destroy();
+                reject(new Error("Request body too large"));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            try {
+                resolve(JSON.parse(Buffer.concat(chunks).toString()));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        req.on("error", reject);
+    });
+}
+export function validateMcporterServerName(name) {
+    const trimmed = name.trim();
+    if (!/^[a-zA-Z0-9_-]+$/.test(trimmed)) {
+        throw new Error("Invalid mcporter server name.");
+    }
+    return trimmed;
+}
+function bearerToken(req) {
+    const auth = headerValue(req, "authorization");
+    if (!auth)
+        return "";
+    const match = /^Bearer\s+(.+)$/i.exec(auth);
+    return match?.[1]?.trim() ?? "";
+}
+function resolveInternalAuth(req, serviceSecret) {
+    const internalUserId = headerValue(req, "x-kynver-user-id");
+    const internalSecret = headerValue(req, "x-kynver-service-secret");
+    if (!internalUserId || !serviceSecret || !internalSecret)
+        return null;
+    if (!timingSafeEqualString(internalSecret, serviceSecret))
+        return null;
+    return { userId: internalUserId, auth: { kind: "internal", userId: internalUserId } };
+}
+function verifyPostAuth(req, url, sessionAuth, serviceSecret) {
+    if (sessionAuth.kind === "apiKey") {
+        const token = bearerToken(req) || queryApiKey(url);
+        return token.length > 0 && timingSafeEqualString(token, sessionAuth.apiKey);
+    }
+    const internal = resolveInternalAuth(req, serviceSecret);
+    return (internal !== null &&
+        internal.userId === sessionAuth.userId &&
+        internal.auth.kind === "internal");
+}
+async function resolveUserFromApiKey(baseUrl, apiKey) {
+    try {
+        const res = await fetch(`${baseUrl.replace(/\/$/, "")}/api/users/me`, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function parseUrl(req, port) {
+    return new URL(req.url ?? "/", `http://localhost:${port}`);
+}
+function json(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+export function startKynverMcpSseServer(options) {
+    const port = parseInt(process.env.PORT ?? String(options.defaultPort), 10);
+    const baseUrl = process.env.KYNVER_API_URL ?? "https://kynver.com";
+    const serviceSecret = process.env.KYNVER_SERVICE_SECRET ?? "";
+    const host = resolveListenHost();
+    const sessions = {};
+    const httpServer = createServer(async (req, res) => {
+        const url = parseUrl(req, port);
+        const path = url.pathname;
+        if (req.method === "GET" && path === "/sse") {
+            if (hasForbiddenQueryAuth(url)) {
+                json(res, 400, {
+                    error: "Internal auth via query params is not allowed. Use X-Kynver-User-Id and X-Kynver-Service-Secret headers.",
+                });
+                return;
+            }
+            if (url.searchParams.has("apiKey")) {
+                console.warn("[MCP SSE] WARNING: apiKey in query string may leak via logs. Prefer Authorization header when your client supports it.");
+            }
+            let userId = null;
+            let auth = null;
+            const internal = serviceSecret ? resolveInternalAuth(req, serviceSecret) : null;
+            if (internal) {
+                userId = internal.userId;
+                auth = internal.auth;
+            }
+            else {
+                const apiKey = bearerToken(req) || queryApiKey(url);
+                if (apiKey) {
+                    userId = await resolveUserFromApiKey(baseUrl, apiKey);
+                    if (userId)
+                        auth = { kind: "apiKey", apiKey };
+                }
+            }
+            if (!userId || !auth) {
+                json(res, 401, {
+                    error: "Unauthorized. Pass API key via Authorization: Bearer <key> or internal X-Kynver-User-Id + X-Kynver-Service-Secret headers.",
+                });
+                return;
+            }
+            console.log(`[MCP SSE] New connection (${options.label}, user: ${userId.slice(0, 8)}...)`);
+            const transport = new SSEServerTransport("/messages", res);
+            sessions[transport.sessionId] = { transport, userId, auth };
+            res.on("close", () => {
+                delete sessions[transport.sessionId];
+            });
+            const server = await options.createMcpServer();
+            await server.connect(transport);
+            return;
+        }
+        if (req.method === "POST" && path === "/messages") {
+            const sessionId = url.searchParams.get("sessionId");
+            const entry = sessionId ? sessions[sessionId] : undefined;
+            if (!entry) {
+                json(res, 400, { error: "No active SSE session for this sessionId" });
+                return;
+            }
+            if (!verifyPostAuth(req, url, entry.auth, serviceSecret)) {
+                json(res, 401, { error: "Unauthorized. Re-send the same credentials used to open the SSE session." });
+                return;
+            }
+            try {
+                const body = await parseJsonBody(req);
+                await options.requestContext.run({ userId: entry.userId }, async () => {
+                    await entry.transport.handlePostMessage(req, res, body);
+                });
+            }
+            catch (error) {
+                json(res, 400, {
+                    error: error instanceof Error ? error.message : "Invalid request body",
+                });
+            }
+            return;
+        }
+        if (req.method === "GET" && path === "/health") {
+            res.writeHead(200, { "Content-Type": "text/plain" });
+            res.end("ok");
+            return;
+        }
+        json(res, 404, { error: "Not found" });
+    });
+    httpServer.listen(port, host, () => {
+        console.log(`[MCP SSE] ${options.label} listening on ${host}:${port}`);
+    });
+}

package/dist/server.js

@@ -69,6 +69,10 @@ export function createAgentOsServer() {
         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 memorySurfaceField = z
+        .enum(["operator", "customer"])
+        .optional()
+        .describe("Response shape for memory reads. Owners/env admins may pass operator for full diagnostics or customer to preview grantee-safe JSON. Grantees always receive customer-safe fields regardless of this flag.");
     const sourceRefSchema = z
         .object({
         type: z
@@ -130,6 +134,7 @@ export function createAgentOsServer() {
         memoryQuery: z.string().optional().describe("Override the memory search query. Defaults to a query derived from the anchor's title/summary."),
         memoryLimit: z.number().optional().describe("Max memory hits (default 5, max 20). Set 0 to skip memory recall."),
         sessionLimit: z.number().optional().describe("Max recent sessions (default 1, max 5). Set 0 to skip."),
+        surface: memorySurfaceField,
         slug: slugField,
     }, async (args) => {
         const s = await resolveToolSlug(args.slug);
@@ -142,6 +147,8 @@ export function createAgentOsServer() {
             params.set("memoryLimit", String(args.memoryLimit));
         if (args.sessionLimit !== undefined)
             params.set("sessionLimit", String(args.sessionLimit));
+        if (args.surface)
+            params.set("surface", args.surface);
         return jsonResult(await get(`/agent-os/${s}/context-envelope?${params}`));
     });
     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.", {
@@ -269,7 +276,7 @@ export function createAgentOsServer() {
         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. Optionally restrict to one source namespace via sourceId, or several via sourceIds (sourceId takes precedence when both are set). 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.", {
+    register("agent_os_search_memory", "Semantic + keyword hybrid search over the agent's long-term memory (ownerType=agent). Use to recall specific decisions, project details, or lessons without loading full context. Replaces grep/reading MEMORY.md. Optionally restrict to one source namespace via sourceId, or several via sourceIds (sourceId takes precedence when both are set). Workspace owners and env admins receive operator diagnostics (rrfScore, lanes, hygiene) unless surface=customer; grantees always receive grantee-safe hits (content, trust, evidence links only).", {
         query: z.string().describe("Natural language query to search memory."),
         k: z.number().optional().describe("Number of results (default 10, max 50)."),
         sourceId: z
@@ -282,6 +289,8 @@ export function createAgentOsServer() {
             .describe("Restrict search to any of these source namespaces. Ignored when sourceId is also set."),
         ticker: z.string().optional().describe("Trading desk: filter hits to this ticker symbol."),
         debatePersona: z.enum(["bull", "bear"]).optional().describe("Trading desk: filter to bull or bear advocate memories."),
+        personaSlug: z.string().optional().describe("Layer in this persona's operating rules in Lane A alongside global rules."),
+        surface: memorySurfaceField,
         slug: slugField,
     }, async (args) => {
         const params = new URLSearchParams({ q: args.query });
@@ -297,6 +306,10 @@ export function createAgentOsServer() {
             params.set("ticker", args.ticker);
         if (args.debatePersona)
             params.set("debatePersona", args.debatePersona);
+        if (args.personaSlug)
+            params.set("personaSlug", args.personaSlug);
+        if (args.surface)
+            params.set("surface", args.surface);
         const s = await resolveToolSlug(args.slug);
         return jsonResult(await get(`/agent-os/${s}/memory?${params}`));
     });
@@ -408,6 +421,14 @@ export function createAgentOsServer() {
         goalId: z.string().optional().describe("AgentOS goal id this memory supports, when known."),
         contactId: z.string().optional().describe("AgentOS contact id this memory concerns, when known."),
         skillId: z.string().optional().describe("Skill identifier this memory belongs to. Built-ins use skill slug; user-authored skills use AgentSkill.id."),
+        correctionReason: z
+            .string()
+            .optional()
+            .describe("When this write encodes a user/operator correction (e.g. Telegram preference fix), explain why — triggers memory-quality negative feedback."),
+        correctionSource: z
+            .enum(["telegram", "manual", "api", "session"])
+            .optional()
+            .describe("Channel that supplied the correction; stored in metadata for audit, not memory body."),
         slug: slugField,
     }, async (args) => {
         const categoryToSourceId = {
@@ -440,6 +461,10 @@ export function createAgentOsServer() {
             body.contactId = args.contactId;
         if (args.skillId)
             body.skillId = args.skillId;
+        if (args.correctionReason)
+            body.correctionReason = args.correctionReason;
+        if (args.correctionSource)
+            body.correctionSource = args.correctionSource;
         const s = await resolveToolSlug(args.slug);
         return jsonResult(await post(`/agent-os/${s}/memory`, body));
     });
@@ -536,9 +561,17 @@ export function createAgentOsServer() {
         goalId: z.string().optional(),
         contactId: z.string().optional(),
         skillId: z.string().optional().describe("Skill identifier this memory belongs to. Built-ins use skill slug; user-authored skills use AgentSkill.id."),
+        correctionReason: z
+            .string()
+            .optional()
+            .describe("Why this update corrects prior memory — triggers memory-quality negative feedback when set."),
+        correctionSource: z
+            .enum(["telegram", "manual", "api", "session"])
+            .optional()
+            .describe("Channel that supplied the correction."),
         slug: slugField,
     }, async (args) => {
-        const { key, slug, content, sourceId, metadata, sourceRefs, memoryType, confidence, reviewStatus, projectId, goalId, contactId, skillId } = args;
+        const { key, slug, content, sourceId, metadata, sourceRefs, memoryType, confidence, reviewStatus, projectId, goalId, contactId, skillId, correctionReason, correctionSource } = args;
         const body = { content, slug: key };
         if (sourceId)
             body.sourceId = sourceId;
@@ -560,6 +593,10 @@ export function createAgentOsServer() {
             body.contactId = contactId;
         if (skillId)
             body.skillId = skillId;
+        if (correctionReason)
+            body.correctionReason = correctionReason;
+        if (correctionSource)
+            body.correctionSource = correctionSource;
         const s = await resolveToolSlug(slug);
         return jsonResult(await post(`/agent-os/${s}/memory`, body));
     });
@@ -579,6 +616,7 @@ export function createAgentOsServer() {
         goalId: z.string().optional(),
         contactId: z.string().optional(),
         skillId: z.string().optional(),
+        correctionSource: z.enum(["telegram", "manual", "api", "session"]).optional(),
         slug: slugField,
     }, async (args) => {
         const { slug, ...body } = args;
@@ -607,9 +645,10 @@ export function createAgentOsServer() {
         entityType: activeStateEntityTypeSchema.optional(),
         projectId: z.string().optional(),
         limit: z.number().optional(),
+        surface: memorySurfaceField,
         slug: slugField,
     }, async (args) => {
-        const { slug, entityKey, entityType, projectId, limit } = args;
+        const { slug, entityKey, entityType, projectId, limit, surface } = args;
         const s = await resolveToolSlug(slug);
         const qs = new URLSearchParams();
         if (entityKey)
@@ -620,6 +659,8 @@ export function createAgentOsServer() {
             qs.set("projectId", projectId);
         if (limit !== undefined)
             qs.set("limit", String(limit));
+        if (surface)
+            qs.set("surface", surface);
         const suffix = qs.toString() ? "?" + qs.toString() : "";
         return jsonResult(await get("/agent-os/" + s + "/memory/state" + suffix));
     });

package/dist/sse.js

@@ -1,4 +1,4 @@
-import { startKynverMcpSseServer } from "@kynver-app/mcp-sse-lib";
+import { startKynverMcpSseServer } from "./lib/mcp-sse-server.js";
 import { createAgentOsServer } from "./server.js";
 import { requestContext } from "./lib/kynver-client.js";
 startKynverMcpSseServer({

package/package.json

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