@cencori/mcp 0.2.0 → 0.5.0

package/dist/index.mjs

@@ -199,6 +199,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
@@ -217,6 +227,12 @@ var WRITE_ANNOTATIONS = {
   destructiveHint: false,
   openWorldHint: false
 };
+var DESTRUCTIVE_ANNOTATIONS = {
+  title: "Destructive",
+  readOnlyHint: false,
+  destructiveHint: true,
+  openWorldHint: false
+};
 function jsonResult(data) {
   return {
     content: [
@@ -281,6 +297,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
@@ -338,7 +376,13 @@ function registerGatewayTools(server, client) {
 
 // src/tools/agents.ts
 import { z as z3 } from "zod";
-function registerAgentsTools(server, client) {
+var agentConfigShape = z3.object({
+  model: z3.string().optional(),
+  system_prompt: z3.string().optional(),
+  tools: z3.array(z3.string()).optional(),
+  temperature: z3.number().min(0).max(2).optional()
+}).optional().describe("Agent runtime config: model, system_prompt, tools, temperature.");
+function registerAgentsTools(server, client, caps) {
   server.registerTool(
     "list_agents",
     {
@@ -377,45 +421,110 @@ function registerAgentsTools(server, client) {
     },
     async () => jsonResult(await client.get("/v1/agent/actions/poll"))
   );
+  if (caps.write) {
+    server.registerTool(
+      "create_agent",
+      {
+        title: "Create an agent",
+        description: "Create a new agent in a project.",
+        inputSchema: {
+          project_id: z3.string().min(1).describe("The project id to create the agent in."),
+          name: z3.string().min(1).describe("Agent name."),
+          description: z3.string().optional(),
+          config: agentConfigShape
+        },
+        annotations: WRITE_ANNOTATIONS
+      },
+      async ({ project_id, name, description, config }) => jsonResult(await client.post("/v1/agents", { project_id, name, description, config }))
+    );
+    server.registerTool(
+      "update_agent",
+      {
+        title: "Update an agent",
+        description: "Update an agent\u2019s name, description, status, shadow mode, or config.",
+        inputSchema: {
+          agent_id: z3.string().min(1).describe("The agent id to update."),
+          name: z3.string().optional(),
+          description: z3.string().optional(),
+          is_active: z3.boolean().optional(),
+          shadow_mode: z3.boolean().optional(),
+          config: agentConfigShape
+        },
+        annotations: WRITE_ANNOTATIONS
+      },
+      async ({ agent_id, name, description, is_active, shadow_mode, config }) => jsonResult(
+        await client.patch(`/v1/agents/${agent_id}`, {
+          name,
+          description,
+          is_active,
+          shadow_mode,
+          config
+        })
+      )
+    );
+  }
+  if (caps.destructive) {
+    server.registerTool(
+      "delete_agent",
+      {
+        title: "Delete an agent",
+        description: "Permanently delete an agent by id. This cannot be undone.",
+        inputSchema: { agent_id: z3.string().min(1).describe("The agent id to delete.") },
+        annotations: DESTRUCTIVE_ANNOTATIONS
+      },
+      async ({ agent_id }) => jsonResult(await client.del(`/v1/agents/${agent_id}`))
+    );
+  }
 }
 
 // src/tools/memory.ts
 import { z as z4 } from "zod";
 var scopeShape = {
   namespace: z4.string().optional().describe("Memory namespace to scope to."),
-  scope: z4.string().optional().describe("Memory scope (e.g. project, user, session)."),
-  user_id: z4.string().optional().describe("Scope to a specific end-user id."),
-  session_id: z4.string().optional().describe("Scope to a specific session id.")
+  scope: z4.enum(["user", "session"]).optional().describe('Memory scope. Defaults to "user".'),
+  user_id: z4.string().optional().describe("End-user id. REQUIRED for user scope (the default)."),
+  session_id: z4.string().optional().describe("Session id. REQUIRED for session scope.")
 };
-function registerMemoryTools(server, client) {
+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: z4.number().int().positive().max(200).optional(),
+        limit: z4.number().int().positive().max(100).optional(),
         cursor: z4.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: z4.string().min(1).describe("Natural-language search query."),
         ...scopeShape,
@@ -424,17 +533,21 @@ function registerMemoryTools(server, client) {
       },
       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",
@@ -450,24 +563,23 @@ function registerMemoryTools(server, client) {
     "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: z4.string().optional().describe("Entity to start traversal from."),
@@ -475,39 +587,137 @@ function registerMemoryTools(server, client) {
       },
       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. Requires user_id (or session_id for session scope).",
+        inputSchema: {
+          user: z4.string().min(1).describe("The user message."),
+          assistant: z4.string().min(1).describe("The assistant response."),
+          ...scopeShape
+        },
+        annotations: WRITE_ANNOTATIONS
+      },
+      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). Requires user_id (or session_id for session scope).",
+        inputSchema: {
+          content: z4.string().min(1).describe("The memory content to store."),
+          importance: z4.number().min(0).max(1).optional().describe("Importance weight 0\u20131."),
+          ...scopeShape
+        },
+        annotations: WRITE_ANNOTATIONS
+      },
+      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",
+      {
+        title: "Create a memory namespace",
+        description: "Create a new memory namespace.",
+        inputSchema: {
+          name: z4.string().min(1).describe("Namespace name."),
+          description: z4.string().optional(),
+          embedding_model: z4.string().optional().describe("Embedding model for this namespace."),
+          dimensions: z4.number().int().positive().optional()
+        },
+        annotations: WRITE_ANNOTATIONS
+      },
+      async ({ name, description, embedding_model, dimensions }) => jsonResult(
+        await client.post("/memory/namespaces", {
+          name,
+          description,
+          embeddingModel: embedding_model,
+          dimensions
+        })
+      )
+    );
+  }
+  if (caps.destructive) {
+    server.registerTool(
+      "delete_memory",
+      {
+        title: "Delete a memory",
+        description: "Permanently delete a memory by id. This cannot be undone.",
+        inputSchema: { memory_id: z4.string().min(1).describe("The memory id to delete.") },
+        annotations: DESTRUCTIVE_ANNOTATIONS
+      },
+      async ({ memory_id }) => jsonResult(await client.del(`/v1/memory/${memory_id}`))
+    );
+  }
 }
 
 // src/tools/sessions.ts
 import { z as z5 } from "zod";
-function registerSessionsTools(server, client) {
+function registerSessionsTools(server, client, caps) {
   server.registerTool(
     "list_sessions",
     {
@@ -550,11 +760,87 @@ function registerSessionsTools(server, client) {
     },
     async ({ session_id }) => jsonResult(await client.get(`/v1/sessions/${session_id}/events`))
   );
+  if (caps.write) {
+    server.registerTool(
+      "create_session",
+      {
+        title: "Create an agent session",
+        description: "Start a new session for an agent.",
+        inputSchema: {
+          agent_id: z5.string().min(1).describe("The agent id to start a session for."),
+          metadata: z5.record(z5.string(), z5.unknown()).optional().describe("Optional session metadata.")
+        },
+        annotations: WRITE_ANNOTATIONS
+      },
+      async ({ agent_id, metadata }) => jsonResult(await client.post("/v1/sessions", { agent_id, metadata }))
+    );
+    server.registerTool(
+      "add_session_turn",
+      {
+        title: "Add a turn to a session",
+        description: "Run a turn in an agent session. Incurs usage/cost.",
+        inputSchema: {
+          session_id: z5.string().min(1).describe("The session id."),
+          model: z5.string().min(1).describe("Model id for the turn."),
+          input: z5.string().min(1).describe("The user input for this turn."),
+          instructions: z5.string().optional().describe("Optional system instructions."),
+          temperature: z5.number().min(0).max(2).optional()
+        },
+        annotations: WRITE_ANNOTATIONS
+      },
+      async ({ session_id, model, input, instructions, temperature }) => jsonResult(
+        await client.post(`/v1/sessions/${session_id}/turns`, {
+          model,
+          input,
+          instructions,
+          temperature
+        })
+      )
+    );
+  }
+  if (caps.destructive) {
+    server.registerTool(
+      "delete_session",
+      {
+        title: "Delete an agent session",
+        description: "Permanently delete an agent session by id. This cannot be undone.",
+        inputSchema: { session_id: z5.string().min(1).describe("The session id to delete.") },
+        annotations: DESTRUCTIVE_ANNOTATIONS
+      },
+      async ({ session_id }) => jsonResult(await client.del(`/v1/sessions/${session_id}`))
+    );
+    server.registerTool(
+      "approve_session",
+      {
+        title: "Approve a pending session action",
+        description: "Approve a pending action in an agent session (human-in-the-loop).",
+        inputSchema: {
+          session_id: z5.string().min(1).describe("The session id."),
+          action_id: z5.string().optional().describe("Specific pending action id, if any.")
+        },
+        annotations: DESTRUCTIVE_ANNOTATIONS
+      },
+      async ({ session_id, action_id }) => jsonResult(await client.post(`/v1/sessions/${session_id}/approve`, { action_id }))
+    );
+    server.registerTool(
+      "reject_session",
+      {
+        title: "Reject a pending session action",
+        description: "Reject a pending action in an agent session (human-in-the-loop).",
+        inputSchema: {
+          session_id: z5.string().min(1).describe("The session id."),
+          action_id: z5.string().optional().describe("Specific pending action id, if any.")
+        },
+        annotations: DESTRUCTIVE_ANNOTATIONS
+      },
+      async ({ session_id, action_id }) => jsonResult(await client.post(`/v1/sessions/${session_id}/reject`, { action_id }))
+    );
+  }
 }
 
 // src/tools/governance.ts
 import { z as z6 } from "zod";
-function registerGovernanceTools(server, client) {
+function registerGovernanceTools(server, client, caps) {
   server.registerTool(
     "list_policies",
     {
@@ -617,6 +903,34 @@ function registerGovernanceTools(server, client) {
     },
     async () => jsonResult(await client.get("/v1/governance/templates"))
   );
+  if (caps.write) {
+    server.registerTool(
+      "create_policy",
+      {
+        title: "Draft a governance policy",
+        description: "Create a governance policy as a DRAFT. It is not enforced until a human activates it (see how_to_activate_policy).",
+        inputSchema: {
+          name: z6.string().min(1).describe("Policy name (unique per org)."),
+          spec: z6.record(z6.string(), z6.unknown()).describe("Policy spec object: match + rules + defaults + controls.")
+        },
+        annotations: WRITE_ANNOTATIONS
+      },
+      async ({ name, spec }) => jsonResult(await client.post("/v1/governance/policies", { name, spec }))
+    );
+    server.registerTool(
+      "install_template",
+      {
+        title: "Install a governance policy template",
+        description: "Install a policy template as a new DRAFT policy. Activation remains a manual human step (see how_to_activate_policy).",
+        inputSchema: {
+          template_id: z6.string().min(1).describe("The template id to install."),
+          name: z6.string().min(1).describe("Name for the new draft policy.")
+        },
+        annotations: WRITE_ANNOTATIONS
+      },
+      async ({ template_id, name }) => jsonResult(await client.post(`/v1/governance/templates/${template_id}/install`, { name }))
+    );
+  }
 }
 
 // src/tools/multimodal.ts
@@ -899,7 +1213,7 @@ function registerGuidanceTools(server, baseUrl) {
 
 // src/server.ts
 var SERVER_NAME = "cencori";
-var SERVER_VERSION = "0.2.0";
+var SERVER_VERSION = "0.5.0";
 function createServer(config) {
   const server = new McpServer(
     {
@@ -924,10 +1238,10 @@ function createServer(config) {
   if (config.apiKey) {
     const client = new PlatformClient(config.baseUrl, config.apiKey);
     if (features.gateway) registerGatewayTools(server, client);
-    if (features.agents) registerAgentsTools(server, client);
-    if (features.memory) registerMemoryTools(server, client);
-    if (features.sessions) registerSessionsTools(server, client);
-    if (features.governance) registerGovernanceTools(server, client);
+    if (features.agents) registerAgentsTools(server, client, capabilities);
+    if (features.memory) registerMemoryTools(server, client, capabilities);
+    if (features.sessions) registerSessionsTools(server, client, capabilities);
+    if (features.governance) registerGovernanceTools(server, client, capabilities);
     if (features.multimodal && capabilities.write) {
       registerMultimodalTools(server, client);
     }