@cencori/mcp 0.2.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) |
@@ -57,11 +58,19 @@ Docs + `how_to_*` guidance tools work with **no API key**. Add `CENCORI_API_KEY`
 | Sessions | `list_sessions`, `get_session`, `get_session_events` |
 | Governance | `list_policies`, `list_roles`, `list_change_requests`, `get_governance_ledger`, `get_governance_evidence`, `list_governance_templates` |
 
-### Inference (Write-tier) — requires `CENCORI_MCP_WRITE=1`
+### Write — requires `CENCORI_MCP_WRITE=1`
 
-`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`.
+- **Memory:** `remember_memory`, `write_memory`, `create_namespace`.
+- **Agents:** `create_agent`, `update_agent`.
+- **Sessions:** `create_session`, `add_session_turn`.
+- **Governance (draft only):** `create_policy`, `install_template`. Policies are created as **drafts** — activation stays a manual human step (`how_to_activate_policy`).
 
-> Roadmap: Phase 2 adds memory/agent/session write + destructive tools; Phase 3 adds governance policy *drafting*. Audio (TTS/STT) is planned once binary/multipart transport lands.
+### Destructive — requires `CENCORI_MCP_DESTRUCTIVE=1` (implies write)
+
+`delete_memory`, `delete_agent`, `delete_session`, `approve_session`, `reject_session`. All carry `destructiveHint` so clients can confirm.
+
+> Roadmap: audio (TTS/STT) once binary/multipart transport lands.
 
 ---
 
@@ -122,11 +131,12 @@ See [`mcp.example.json`](./mcp.example.json) for a copy-paste template.
 
 ### Behavior
 
-| `CENCORI_API_KEY` | `CENCORI_MCP_WRITE` | Registered |
-|-------------------|---------------------|-----------|
+| `CENCORI_API_KEY` | Flag | Registered |
+|-------------------|------|-----------|
 | unset | — | docs + `how_to_*` guidance only |
-| set | unset | guidance + all **reads** |
-| set | `1` | guidance + reads + **inference** |
+| set | — | guidance + all **reads** |
+| set | `CENCORI_MCP_WRITE=1` | + **writes** (inference, memory, agents, sessions) |
+| set | `CENCORI_MCP_DESTRUCTIVE=1` | + **destructive** (delete/approve/reject); implies write |
 
 Restart the MCP server after changing env vars.
 

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
@@ -218,6 +228,12 @@ var WRITE_ANNOTATIONS = {
   destructiveHint: false,
   openWorldHint: false
 };
+var DESTRUCTIVE_ANNOTATIONS = {
+  title: "Destructive",
+  readOnlyHint: false,
+  destructiveHint: true,
+  openWorldHint: false
+};
 function jsonResult(data) {
   return {
     content: [
@@ -282,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
@@ -339,7 +377,13 @@ function registerGatewayTools(server, client) {
 
 // src/tools/agents.ts
 var import_zod3 = require("zod");
-function registerAgentsTools(server, client) {
+var agentConfigShape = import_zod3.z.object({
+  model: import_zod3.z.string().optional(),
+  system_prompt: import_zod3.z.string().optional(),
+  tools: import_zod3.z.array(import_zod3.z.string()).optional(),
+  temperature: import_zod3.z.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",
     {
@@ -378,45 +422,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: import_zod3.z.string().min(1).describe("The project id to create the agent in."),
+          name: import_zod3.z.string().min(1).describe("Agent name."),
+          description: import_zod3.z.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: import_zod3.z.string().min(1).describe("The agent id to update."),
+          name: import_zod3.z.string().optional(),
+          description: import_zod3.z.string().optional(),
+          is_active: import_zod3.z.boolean().optional(),
+          shadow_mode: import_zod3.z.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: import_zod3.z.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
 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 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: 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,
@@ -425,17 +534,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",
@@ -451,24 +564,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: import_zod4.z.string().optional().describe("Entity to start traversal from."),
@@ -476,39 +588,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: import_zod4.z.string().min(1).describe("The user message."),
+          assistant: import_zod4.z.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: 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."),
+          ...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: import_zod4.z.string().min(1).describe("Namespace name."),
+          description: import_zod4.z.string().optional(),
+          embedding_model: import_zod4.z.string().optional().describe("Embedding model for this namespace."),
+          dimensions: import_zod4.z.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: import_zod4.z.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
 var import_zod5 = require("zod");
-function registerSessionsTools(server, client) {
+function registerSessionsTools(server, client, caps) {
   server.registerTool(
     "list_sessions",
     {
@@ -551,11 +761,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: import_zod5.z.string().min(1).describe("The agent id to start a session for."),
+          metadata: import_zod5.z.record(import_zod5.z.string(), import_zod5.z.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: import_zod5.z.string().min(1).describe("The session id."),
+          model: import_zod5.z.string().min(1).describe("Model id for the turn."),
+          input: import_zod5.z.string().min(1).describe("The user input for this turn."),
+          instructions: import_zod5.z.string().optional().describe("Optional system instructions."),
+          temperature: import_zod5.z.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: import_zod5.z.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: import_zod5.z.string().min(1).describe("The session id."),
+          action_id: import_zod5.z.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: import_zod5.z.string().min(1).describe("The session id."),
+          action_id: import_zod5.z.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
 var import_zod6 = require("zod");
-function registerGovernanceTools(server, client) {
+function registerGovernanceTools(server, client, caps) {
   server.registerTool(
     "list_policies",
     {
@@ -618,6 +904,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: import_zod6.z.string().min(1).describe("Policy name (unique per org)."),
+          spec: import_zod6.z.record(import_zod6.z.string(), import_zod6.z.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: import_zod6.z.string().min(1).describe("The template id to install."),
+          name: import_zod6.z.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
@@ -900,7 +1214,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 import_mcp.McpServer(
     {
@@ -925,10 +1239,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);
     }