@cencori/mcp 0.2.0 → 0.4.0

package/README.md

@@ -57,11 +57,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 +130,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

@@ -218,6 +218,12 @@ var WRITE_ANNOTATIONS = {
   destructiveHint: false,
   openWorldHint: false
 };
+var DESTRUCTIVE_ANNOTATIONS = {
+  title: "Destructive",
+  readOnlyHint: false,
+  destructiveHint: true,
+  openWorldHint: false
+};
 function jsonResult(data) {
   return {
     content: [
@@ -339,7 +345,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,6 +390,60 @@ 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
@@ -388,7 +454,7 @@ var scopeShape = {
   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.")
 };
-function registerMemoryTools(server, client) {
+function registerMemoryTools(server, client, caps) {
   server.registerTool(
     "list_memories",
     {
@@ -504,11 +570,93 @@ function registerMemoryTools(server, client) {
       })
     )
   );
+  if (caps.write) {
+    server.registerTool(
+      "remember_memory",
+      {
+        title: "Remember a conversation turn",
+        description: "Store a user/assistant exchange as memory for later retrieval.",
+        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 }) => 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.",
+        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 }) => 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 +699,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 +842,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 +1152,7 @@ function registerGuidanceTools(server, baseUrl) {
 
 // src/server.ts
 var SERVER_NAME = "cencori";
-var SERVER_VERSION = "0.2.0";
+var SERVER_VERSION = "0.4.0";
 function createServer(config) {
   const server = new import_mcp.McpServer(
     {
@@ -925,10 +1177,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);
     }