@cencori/mcp 0.4.0 → 0.6.0

package/README.md

@@ -42,6 +42,7 @@ Docs + `how_to_*` guidance tools work with **no API key**. Add `CENCORI_API_KEY`
 | Tool | Description |
 |------|-------------|
 | `search_docs` / `get_doc` / `list_docs` | Search / fetch / list Cencori documentation |
+| `get_integration_guide` | Fetch the full `llm.txt` integration contract — the authoritative "how to set up Cencori in a codebase" guide |
 | `how_to_create_api_key`, `how_to_edit_api_key`, `how_to_revoke_api_key` | Guidance: API-key lifecycle (manual) |
 | `how_to_activate_policy`, `how_to_respond_to_change_request` | Guidance: governance checker steps (manual) |
 | `how_to_change_plan`, `how_to_manage_billing` | Guidance: billing / plan / credits (manual) |
@@ -59,7 +60,7 @@ Docs + `how_to_*` guidance tools work with **no API key**. Add `CENCORI_API_KEY`
 
 ### Write — requires `CENCORI_MCP_WRITE=1`
 
-- **Inference:** `generate_text`, `generate_rag`, `create_embeddings`, `moderate_content`, `generate_image`, `describe_image`, `ocr_image`, `classify_image`, `extract_document`, `summarize_document`, `query_document`.
+- **Inference:** `generate_text`, `generate_rag`, `create_embeddings`, `moderate_content`, `generate_image`, `describe_image`, `ocr_image`, `classify_image`, `extract_document`, `summarize_document`, `query_document`, `text_to_speech`, `transcribe_audio`.
 - **Memory:** `remember_memory`, `write_memory`, `create_namespace`.
 - **Agents:** `create_agent`, `update_agent`.
 - **Sessions:** `create_session`, `add_session_turn`.

package/dist/index.js

@@ -148,6 +148,37 @@ var PlatformClient = class {
   del(path) {
     return this.request("DELETE", path);
   }
+  /** POST JSON and read a BINARY response (e.g. TTS audio). Returns base64 + mime. */
+  async postBinary(path, body) {
+    const url = new URL(`/api${path}`, this.baseUrl);
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: fetchSignal()
+    });
+    if (!response.ok) {
+      throw new Error(`Cencori API error: ${await readHttpErrorMessage(response)}`);
+    }
+    const mimeType = response.headers.get("content-type")?.split(";")[0]?.trim() || "application/octet-stream";
+    const buf = Buffer.from(await response.arrayBuffer());
+    return { base64: buf.toString("base64"), mimeType };
+  }
+  /** POST multipart/form-data (e.g. STT audio upload). Let fetch set the boundary. */
+  async postForm(path, form) {
+    const url = new URL(`/api${path}`, this.baseUrl);
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+      body: form,
+      signal: fetchSignal()
+    });
+    if (!response.ok) {
+      throw new Error(`Cencori API error: ${await readHttpErrorMessage(response)}`);
+    }
+    const text = await response.text();
+    return text ? JSON.parse(text) : void 0;
+  }
   listModels() {
     return this.get("/v1/models");
   }
@@ -200,6 +231,16 @@ var DocsClient = class {
     }
     return response.json();
   }
+  /** Fetch the raw `llm.txt` integration contract (public, no auth). */
+  async getIntegrationGuide() {
+    const url = new URL("/llm.txt", this.baseUrl);
+    const response = await fetch(url, { signal: fetchSignal() });
+    if (!response.ok) {
+      const message = await readHttpErrorMessage(response);
+      throw new Error(`Integration guide fetch failed (${response.status}): ${message}`);
+    }
+    return response.text();
+  }
 };
 
 // src/tools/docs.ts
@@ -288,6 +329,28 @@ function registerDocsTools(server, docs, docsBaseUrl) {
       return jsonResult(navigation);
     }
   );
+  server.registerTool(
+    "get_integration_guide",
+    {
+      title: "Get the Cencori integration guide (llm.txt)",
+      description: 'Fetch the full Cencori "Integration Contract for Code Agents" (llm.txt) \u2014 the authoritative, always-current guide for setting up Cencori in a codebase: package names, import paths, env vars, base URLs, SDK usage, request/response shapes, and step-by-step setup. Call this FIRST when asked to add, integrate, or set up Cencori in a project.',
+      inputSchema: {},
+      annotations: READ_ONLY_ANNOTATIONS
+    },
+    async () => {
+      const guide = await docs.getIntegrationGuide();
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Source: ${docsBaseUrl}/llm.txt
+
+${guide}`
+          }
+        ]
+      };
+    }
+  );
 }
 
 // src/tools/gateway.ts
@@ -450,39 +513,50 @@ function registerAgentsTools(server, client, caps) {
 var import_zod4 = require("zod");
 var scopeShape = {
   namespace: import_zod4.z.string().optional().describe("Memory namespace to scope to."),
-  scope: import_zod4.z.string().optional().describe("Memory scope (e.g. project, user, session)."),
-  user_id: import_zod4.z.string().optional().describe("Scope to a specific end-user id."),
-  session_id: import_zod4.z.string().optional().describe("Scope to a specific session id.")
+  scope: import_zod4.z.enum(["user", "session"]).optional().describe('Memory scope. Defaults to "user".'),
+  user_id: import_zod4.z.string().optional().describe("End-user id. REQUIRED for user scope (the default)."),
+  session_id: import_zod4.z.string().optional().describe("Session id. REQUIRED for session scope.")
 };
+function missingScopeKey({ scope, user_id, session_id }) {
+  if ((scope ?? "user") === "session") {
+    return session_id || user_id ? null : "session_id (or user_id) is required for session scope.";
+  }
+  return user_id ? null : 'user_id is required for user scope (the default). Pass user_id, or use scope="session" with session_id.';
+}
+var scopeErr = (msg) => jsonResult({ error: "missing_scope", message: msg });
 function registerMemoryTools(server, client, caps) {
   server.registerTool(
     "list_memories",
     {
       title: "List memories",
-      description: "List stored memories for the project, optionally scoped by namespace/user/session.",
+      description: "List stored memories for a user or session. Requires user_id (or session_id for session scope).",
       inputSchema: {
         ...scopeShape,
-        limit: import_zod4.z.number().int().positive().max(200).optional(),
+        limit: import_zod4.z.number().int().positive().max(100).optional(),
         cursor: import_zod4.z.string().optional().describe("Pagination cursor from a previous response.")
       },
       annotations: READ_ONLY_ANNOTATIONS
     },
-    async ({ namespace, scope, user_id, session_id, limit, cursor }) => jsonResult(
-      await client.get("/v1/memory/list", {
-        namespace,
-        scope,
-        userId: user_id,
-        sessionId: session_id,
-        limit: limit?.toString(),
-        cursor
-      })
-    )
+    async ({ namespace, scope, user_id, session_id, limit, cursor }) => {
+      const err = missingScopeKey({ scope, user_id, session_id });
+      if (err) return scopeErr(err);
+      return jsonResult(
+        await client.get("/v1/memory/list", {
+          namespace,
+          scope,
+          userId: user_id,
+          sessionId: session_id,
+          limit: limit?.toString(),
+          cursor
+        })
+      );
+    }
   );
   server.registerTool(
     "search_memory",
     {
       title: "Search memory (semantic)",
-      description: "Semantically search stored memories by query.",
+      description: "Semantically search a user\u2019s or session\u2019s memories. Requires user_id (or session_id for session scope).",
       inputSchema: {
         query: import_zod4.z.string().min(1).describe("Natural-language search query."),
         ...scopeShape,
@@ -491,17 +565,21 @@ function registerMemoryTools(server, client, caps) {
       },
       annotations: READ_ONLY_ANNOTATIONS
     },
-    async ({ query, namespace, scope, user_id, session_id, top_k, threshold }) => jsonResult(
-      await client.post("/v1/memory/search", {
-        query,
-        namespace,
-        scope,
-        userId: user_id,
-        sessionId: session_id,
-        topK: top_k,
-        threshold
-      })
-    )
+    async ({ query, namespace, scope, user_id, session_id, top_k, threshold }) => {
+      const err = missingScopeKey({ scope, user_id, session_id });
+      if (err) return scopeErr(err);
+      return jsonResult(
+        await client.post("/v1/memory/search", {
+          query,
+          namespace,
+          scope,
+          userId: user_id,
+          sessionId: session_id,
+          topK: top_k,
+          threshold
+        })
+      );
+    }
   );
   server.registerTool(
     "get_memory",
@@ -517,24 +595,23 @@ function registerMemoryTools(server, client, caps) {
     "list_memory_entities",
     {
       title: "List memory entities",
-      description: "List entities resolved from the memory graph.",
+      description: "List entities resolved from a user\u2019s or session\u2019s memory graph. Requires user_id (or session_id).",
       inputSchema: scopeShape,
       annotations: READ_ONLY_ANNOTATIONS
     },
-    async ({ namespace, scope, user_id, session_id }) => jsonResult(
-      await client.get("/v1/memory/entities", {
-        namespace,
-        scope,
-        userId: user_id,
-        sessionId: session_id
-      })
-    )
+    async ({ namespace, scope, user_id, session_id }) => {
+      const err = missingScopeKey({ scope, user_id, session_id });
+      if (err) return scopeErr(err);
+      return jsonResult(
+        await client.get("/v1/memory/entities", { namespace, scope, userId: user_id, sessionId: session_id })
+      );
+    }
   );
   server.registerTool(
     "get_memory_graph",
     {
       title: "Get memory entity graph",
-      description: "Traverse the memory entity graph from an optional starting entity.",
+      description: "Traverse a user\u2019s or session\u2019s memory entity graph. Requires user_id (or session_id).",
       inputSchema: {
         ...scopeShape,
         entity: import_zod4.z.string().optional().describe("Entity to start traversal from."),
@@ -542,40 +619,48 @@ function registerMemoryTools(server, client, caps) {
       },
       annotations: READ_ONLY_ANNOTATIONS
     },
-    async ({ namespace, scope, user_id, session_id, entity, hops }) => jsonResult(
-      await client.get("/v1/memory/graph", {
-        namespace,
-        scope,
-        userId: user_id,
-        sessionId: session_id,
-        entity,
-        hops: hops?.toString()
-      })
-    )
+    async ({ namespace, scope, user_id, session_id, entity, hops }) => {
+      const err = missingScopeKey({ scope, user_id, session_id });
+      if (err) return scopeErr(err);
+      return jsonResult(
+        await client.get("/v1/memory/graph", {
+          namespace,
+          scope,
+          userId: user_id,
+          sessionId: session_id,
+          entity,
+          hops: hops?.toString()
+        })
+      );
+    }
   );
   server.registerTool(
     "get_forget_suggestions",
     {
       title: "Get forget suggestions",
-      description: "List memories the system suggests forgetting (stale/superseded).",
+      description: "List memories the system suggests forgetting for a user or session. Requires user_id (or session_id).",
       inputSchema: scopeShape,
       annotations: READ_ONLY_ANNOTATIONS
     },
-    async ({ namespace, scope, user_id, session_id }) => jsonResult(
-      await client.get("/v1/memory/forget-suggestions", {
-        namespace,
-        scope,
-        userId: user_id,
-        sessionId: session_id
-      })
-    )
+    async ({ namespace, scope, user_id, session_id }) => {
+      const err = missingScopeKey({ scope, user_id, session_id });
+      if (err) return scopeErr(err);
+      return jsonResult(
+        await client.get("/v1/memory/forget-suggestions", {
+          namespace,
+          scope,
+          userId: user_id,
+          sessionId: session_id
+        })
+      );
+    }
   );
   if (caps.write) {
     server.registerTool(
       "remember_memory",
       {
         title: "Remember a conversation turn",
-        description: "Store a user/assistant exchange as memory for later retrieval.",
+        description: "Store a user/assistant exchange as memory. Requires user_id (or session_id for session scope).",
         inputSchema: {
           user: import_zod4.z.string().min(1).describe("The user message."),
           assistant: import_zod4.z.string().min(1).describe("The assistant response."),
@@ -583,22 +668,26 @@ function registerMemoryTools(server, client, caps) {
         },
         annotations: WRITE_ANNOTATIONS
       },
-      async ({ user, assistant, namespace, scope, user_id, session_id }) => jsonResult(
-        await client.post("/v1/memory/remember", {
-          user,
-          assistant,
-          namespace,
-          scope,
-          userId: user_id,
-          sessionId: session_id
-        })
-      )
+      async ({ user, assistant, namespace, scope, user_id, session_id }) => {
+        const err = missingScopeKey({ scope, user_id, session_id });
+        if (err) return scopeErr(err);
+        return jsonResult(
+          await client.post("/v1/memory/remember", {
+            user,
+            assistant,
+            namespace,
+            scope,
+            userId: user_id,
+            sessionId: session_id
+          })
+        );
+      }
     );
     server.registerTool(
       "write_memory",
       {
         title: "Write a memory",
-        description: "Store a single memory (a fact/note) directly.",
+        description: "Store a single memory (a fact/note). Requires user_id (or session_id for session scope).",
         inputSchema: {
           content: import_zod4.z.string().min(1).describe("The memory content to store."),
           importance: import_zod4.z.number().min(0).max(1).optional().describe("Importance weight 0\u20131."),
@@ -606,16 +695,20 @@ function registerMemoryTools(server, client, caps) {
         },
         annotations: WRITE_ANNOTATIONS
       },
-      async ({ content, importance, namespace, scope, user_id, session_id }) => jsonResult(
-        await client.post("/v1/memory/write", {
-          content,
-          importance,
-          namespace,
-          scope,
-          userId: user_id,
-          sessionId: session_id
-        })
-      )
+      async ({ content, importance, namespace, scope, user_id, session_id }) => {
+        const err = missingScopeKey({ scope, user_id, session_id });
+        if (err) return scopeErr(err);
+        return jsonResult(
+          await client.post("/v1/memory/write", {
+            content,
+            importance,
+            namespace,
+            scope,
+            userId: user_id,
+            sessionId: session_id
+          })
+        );
+      }
     );
     server.registerTool(
       "create_namespace",
@@ -1017,11 +1110,77 @@ function registerMultimodalTools(server, client) {
   );
 }
 
-// src/tools/guidance.ts
+// src/tools/audio.ts
 var import_zod8 = require("zod");
+function registerAudioTools(server, client) {
+  server.registerTool(
+    "text_to_speech",
+    {
+      title: "Text to speech",
+      description: "Synthesize speech from text. Returns audio. Incurs usage/cost.",
+      inputSchema: {
+        input: import_zod8.z.string().min(1).describe("The text to speak."),
+        model: import_zod8.z.string().optional().describe("TTS model. Defaults to tts-1."),
+        voice: import_zod8.z.string().optional().describe("Voice id/name (provider-specific)."),
+        response_format: import_zod8.z.string().optional().describe("Audio format, e.g. mp3, wav, opus."),
+        provider: import_zod8.z.string().optional().describe("Override the TTS provider.")
+      },
+      annotations: WRITE_ANNOTATIONS
+    },
+    async ({ input, model, voice, response_format, provider }) => {
+      const { base64, mimeType } = await client.postBinary("/ai/audio/speech", {
+        input,
+        model,
+        voice,
+        response_format,
+        provider
+      });
+      return {
+        content: [
+          { type: "audio", data: base64, mimeType },
+          { type: "text", text: `Synthesized ${input.length} chars \u2192 ${mimeType} (${base64.length} b64 bytes).` }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "transcribe_audio",
+    {
+      title: "Transcribe audio (speech to text)",
+      description: "Transcribe base64-encoded audio to text. Incurs usage/cost.",
+      inputSchema: {
+        audio_base64: import_zod8.z.string().min(1).describe("Base64-encoded audio bytes."),
+        mime_type: import_zod8.z.string().optional().describe("Audio MIME type, e.g. audio/mpeg, audio/wav."),
+        filename: import_zod8.z.string().optional().describe("Original filename (helps format detection)."),
+        model: import_zod8.z.string().optional().describe("STT model. Defaults to whisper-1."),
+        language: import_zod8.z.string().optional().describe("ISO language code, e.g. en."),
+        prompt: import_zod8.z.string().optional().describe("Optional prompt to guide transcription."),
+        response_format: import_zod8.z.enum(["json", "text", "srt", "verbose_json", "vtt"]).optional().describe("Transcript format. verbose_json adds segments/words."),
+        temperature: import_zod8.z.number().min(0).max(1).optional(),
+        provider: import_zod8.z.string().optional().describe("Override the STT provider.")
+      },
+      annotations: WRITE_ANNOTATIONS
+    },
+    async ({ audio_base64, mime_type, filename, model, language, prompt, response_format, temperature, provider }) => {
+      const bytes = Buffer.from(audio_base64, "base64");
+      const form = new FormData();
+      form.append("file", new Blob([bytes], { type: mime_type || "application/octet-stream" }), filename || "audio");
+      if (model) form.append("model", model);
+      if (language) form.append("language", language);
+      if (prompt) form.append("prompt", prompt);
+      if (response_format) form.append("response_format", response_format);
+      if (temperature !== void 0) form.append("temperature", String(temperature));
+      if (provider) form.append("provider", provider);
+      return jsonResult(await client.postForm("/ai/audio/transcriptions", form));
+    }
+  );
+}
+
+// src/tools/guidance.ts
+var import_zod9 = require("zod");
 var orgProjectShape = {
-  org_slug: import_zod8.z.string().min(1).optional().describe("Your organization slug, to build an exact dashboard link."),
-  project_slug: import_zod8.z.string().min(1).optional().describe("Your project slug, to build an exact dashboard link.")
+  org_slug: import_zod9.z.string().min(1).optional().describe("Your organization slug, to build an exact dashboard link."),
+  project_slug: import_zod9.z.string().min(1).optional().describe("Your project slug, to build an exact dashboard link.")
 };
 function registerGuide(server, name, title, description, buildPath, steps, baseUrl) {
   server.registerTool(
@@ -1152,7 +1311,7 @@ function registerGuidanceTools(server, baseUrl) {
 
 // src/server.ts
 var SERVER_NAME = "cencori";
-var SERVER_VERSION = "0.4.0";
+var SERVER_VERSION = "0.6.0";
 function createServer(config) {
   const server = new import_mcp.McpServer(
     {
@@ -1183,6 +1342,7 @@ function createServer(config) {
     if (features.governance) registerGovernanceTools(server, client, capabilities);
     if (features.multimodal && capabilities.write) {
       registerMultimodalTools(server, client);
+      registerAudioTools(server, client);
     }
   }
   return server;