@cencori/mcp 0.4.0 → 0.5.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) |

package/dist/index.js

@@ -200,6 +200,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 +298,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 +482,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 +534,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 +564,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 +588,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 +637,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 +664,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",
@@ -1152,7 +1214,7 @@ function registerGuidanceTools(server, baseUrl) {
 
 // src/server.ts
 var SERVER_NAME = "cencori";
-var SERVER_VERSION = "0.4.0";
+var SERVER_VERSION = "0.5.0";
 function createServer(config) {
   const server = new import_mcp.McpServer(
     {