refactor: move tools to mcp/tools folder

damassi · damassi · commit 5815716a2ff0 · 2025-11-05T09:48:37.000-08:00
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -10,6 +10,7 @@
 - **UI**: React + Ink (terminal UI)
 - **State Management**: Easy-peasy
 - **Agent SDK**: Claude Agent SDK
+- **MCP SDK**: [Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
 - **Language**: TypeScript
 
 ### Core Components
@@ -224,18 +225,21 @@ The CLI can also run as an MCP server itself, exposing the agent as a tool to ot
 
 **Shared MCP Infrastructure:**
 
-- [src/mcp/utils/getMcpServer.ts](../src/mcp/utils/getMcpServer.ts) - MCP server factory
+- [src/mcp/getMcpServer.ts](../src/mcp/getMcpServer.ts) - MCP server factory
   - Creates `McpServer` instance
-  - Registers `ask_agent` tool with Zod validation
-  - Registers `get_agent_status` tool for initialization
+  - Imports and registers tools from individual tool files
   - Shared by both stdio and HTTP modes
-- [src/mcp/utils/runStandaloneAgentLoop.ts](../src/mcp/utils/runStandaloneAgentLoop.ts) - Query execution
+- [src/mcp/tools/](../src/mcp/tools/) - Individual MCP tool definitions
+  - [askAgent.ts](../src/mcp/tools/askAgent.ts) - `ask_agent` tool with Zod validation (general purpose)
+  - [askAgentSlackbot.ts](../src/mcp/tools/askAgentSlackbot.ts) - `ask_agent_slackbot` tool with thread session support
+  - [getAgentStatus.ts](../src/mcp/tools/getAgentStatus.ts) - `get_agent_status` tool for initialization
+- [src/mcp/runStandaloneAgentLoop.ts](../src/mcp/runStandaloneAgentLoop.ts) - Query execution
   - Uses shared `runAgentLoop()` from agent integration
   - Manages message queue and session state
   - Processes streaming responses with logging notifications
   - Implements `onServerConnection` callback for dynamic server selection
   - Returns final text response
-- [src/mcp/utils/getAgentStatus.ts](../src/mcp/utils/getAgentStatus.ts) - Status utility
+- [src/mcp/getAgentStatus.ts](../src/mcp/getAgentStatus.ts) - Status utility
   - Initializes agent to get available MCP servers
   - Called by `get_agent_status` tool on client initialization
   - Returns session ID and MCP servers list
@@ -358,6 +362,44 @@ Uses `cosmiconfig` for flexible configuration loading:
 }
 ```
 
+#### Specialized Subagents
+
+The CLI supports specialized subagents for domain-specific tasks using the [Claude Subagent SDK](https://docs.claude.com/en/docs/claude-code/sub-agents). Subagents are defined in `agent-chat-cli.config.ts` and automatically invoked when user queries match their domain.
+
+**Configuration:**
+
+- [src/utils/createAgent.ts](../src/utils/createAgent.ts) - Subagent factory function
+  - Creates subagent configuration with description, prompt, and MCP servers
+  - Description used by routing agent for intelligent matching
+  - Supports both local prompts (via `getPrompt`) and remote prompts (via `getRemotePrompt`)
+
+**Example:**
+
+```typescript
+agents: {
+  "sales-partner-sentiment-agent": createAgent({
+    description: "An expert SalesForce partner sentiment agent, designed to produce insights for renewal and churn conversations",
+    prompt: getPrompt("agents/sales-partner-sentiment-agent.md"),
+    mcpServers: ["salesforce"],
+  }),
+}
+```
+
+**Flow:**
+
+1. User sends query (e.g., "Analyze partner churn")
+2. Routing agent matches query to subagent based on description
+3. Required MCP servers (e.g., `salesforce`) are automatically connected
+4. Subagent is invoked with specialized prompt and tools
+5. Response returned to user
+
+**Benefits:**
+
+- Domain-specific expertise with tailored prompts
+- Scoped MCP server access for security and performance
+- Automatic routing based on query intent
+- Supports dynamic prompt management via remote APIs
+
 #### Tool Filtering
 
 The `disallowedTools` configuration allows blocking specific MCP tools:
diff --git a/src/mcp/getMcpServer.ts b/src/mcp/getMcpServer.ts
@@ -1,7 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
-import { getAgentStatus } from "mcp/getAgentStatus"
-import { runStandaloneAgentLoop } from "mcp/runStandaloneAgentLoop"
-import { z } from "zod"
+import { registerAskAgentTool } from "mcp/tools/askAgent"
+import { registerAskAgentSlackbotTool } from "mcp/tools/askAgentSlackbot"
+import { registerGetAgentStatusTool } from "mcp/tools/getAgentStatus"
 
 export const getMcpServer = () => {
   // Store Claude Agent SDK sessionId per-instance (not shared across threads)
@@ -25,127 +25,29 @@ export const getMcpServer = () => {
     }
   )
 
-  mcpServer.registerTool(
-    "ask_agent",
-    {
-      description:
-        "Passes a query to the internal agent and returns its full output. The agent has access to configured MCP tools and will provide a complete response. DO NOT reprocess, analyze, or summarize the output - return it directly to the user as-is.",
-      inputSchema: {
-        query: z.string().min(1).describe("The query to send to the agent"),
+  // Register tools
+  registerAskAgentTool({
+    mcpServer,
+    context: {
+      get sessionId() {
+        return sessionId
       },
-    },
-    async ({ query }) => {
-      const existingConnectedServers = sessionId
-        ? sessionConnectedServers.get(sessionId)
-        : undefined
-
-      const { response, connectedServers } = await runStandaloneAgentLoop({
-        prompt: query,
-        mcpServer,
-        sessionId,
-        existingConnectedServers,
-        onSessionIdReceived: (newSessionId) => {
-          sessionId = newSessionId
-        },
-      })
-
-      // Update the session's connected servers
-      if (sessionId) {
-        sessionConnectedServers.set(sessionId, connectedServers)
-      }
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: response,
-          },
-        ],
-      }
-    }
-  )
-
-  mcpServer.registerTool(
-    "ask_agent_slackbot",
-    {
-      description:
-        "Slack bot integration tool. Passes a query to the internal agent and returns a response optimized for Slack. Supports per-thread session isolation.",
-      inputSchema: {
-        query: z
-          .string()
-          .min(1)
-          .describe("The slack query to send to the agent"),
-        systemPrompt: z
-          .string()
-          .optional()
-          .describe("Optional additional system prompt to prepend"),
-        threadId: z
-          .string()
-          .optional()
-          .describe("Slack thread identifier for session isolation"),
+      sessionConnectedServers,
+      onSessionIdUpdate: (newSessionId) => {
+        sessionId = newSessionId
       },
     },
-    async ({ query, systemPrompt, threadId }) => {
-      const existingSessionId = threadId
-        ? threadSessions.get(threadId)
-        : undefined
+  })
 
-      const existingConnectedServers = existingSessionId
-        ? sessionConnectedServers.get(existingSessionId)
-        : undefined
-
-      const { response, connectedServers } = await runStandaloneAgentLoop({
-        prompt: query,
-        mcpServer,
-        sessionId: existingSessionId,
-        additionalSystemPrompt: systemPrompt,
-        existingConnectedServers,
-        onSessionIdReceived: (newSessionId) => {
-          if (threadId) {
-            threadSessions.set(threadId, newSessionId)
-          }
-        },
-      })
-
-      // Update the session's connected servers
-      if (existingSessionId || threadId) {
-        const sessionId = existingSessionId || threadSessions.get(threadId!)
-        if (sessionId) {
-          sessionConnectedServers.set(sessionId, connectedServers)
-        }
-      }
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: response,
-          },
-        ],
-      }
-    }
-  )
-
-  mcpServer.registerTool(
-    "get_agent_status",
-    {
-      description:
-        "Get the status of the agent including which MCP servers it has access to. Call this on initialization to see available servers.",
-      inputSchema: {},
+  registerAskAgentSlackbotTool({
+    mcpServer,
+    context: {
+      threadSessions,
+      sessionConnectedServers,
     },
-    async () => {
-      const status = await getAgentStatus(mcpServer)
+  })
 
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(status, null, 2),
-          },
-        ],
-      }
-    }
-  )
+  registerGetAgentStatusTool({ mcpServer })
 
   return mcpServer
 }
diff --git a/src/mcp/tools/askAgent.ts b/src/mcp/tools/askAgent.ts
@@ -0,0 +1,59 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { runStandaloneAgentLoop } from "mcp/runStandaloneAgentLoop"
+import { z } from "zod"
+
+export interface AskAgentContext {
+  sessionId?: string
+  sessionConnectedServers: Map<string, Set<string>>
+  onSessionIdUpdate: (sessionId: string) => void
+}
+
+export interface RegisterAskAgentToolProps {
+  mcpServer: McpServer
+  context: AskAgentContext
+}
+
+export const registerAskAgentTool = ({
+  mcpServer,
+  context,
+}: RegisterAskAgentToolProps) => {
+  mcpServer.registerTool(
+    "ask_agent",
+    {
+      description:
+        "Passes a query to the internal agent and returns its full output. The agent has access to configured MCP tools and will provide a complete response. DO NOT reprocess, analyze, or summarize the output - return it directly to the user as-is.",
+      inputSchema: {
+        query: z.string().min(1).describe("The query to send to the agent"),
+      },
+    },
+    async ({ query }) => {
+      const existingConnectedServers = context.sessionId
+        ? context.sessionConnectedServers.get(context.sessionId)
+        : undefined
+
+      const { response, connectedServers } = await runStandaloneAgentLoop({
+        prompt: query,
+        mcpServer,
+        sessionId: context.sessionId,
+        existingConnectedServers,
+        onSessionIdReceived: (newSessionId) => {
+          context.onSessionIdUpdate(newSessionId)
+        },
+      })
+
+      // Update the session's connected servers
+      if (context.sessionId) {
+        context.sessionConnectedServers.set(context.sessionId, connectedServers)
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: response,
+          },
+        ],
+      }
+    }
+  )
+}
diff --git a/src/mcp/tools/askAgentSlackbot.ts b/src/mcp/tools/askAgentSlackbot.ts
@@ -0,0 +1,80 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { runStandaloneAgentLoop } from "mcp/runStandaloneAgentLoop"
+import { z } from "zod"
+
+export interface AskAgentSlackbotContext {
+  threadSessions: Map<string, string>
+  sessionConnectedServers: Map<string, Set<string>>
+}
+
+export interface RegisterAskAgentSlackbotToolProps {
+  mcpServer: McpServer
+  context: AskAgentSlackbotContext
+}
+
+export const registerAskAgentSlackbotTool = ({
+  mcpServer,
+  context,
+}: RegisterAskAgentSlackbotToolProps) => {
+  mcpServer.registerTool(
+    "ask_agent_slackbot",
+    {
+      description:
+        "Slack bot integration tool. Passes a query to the internal agent and returns a response optimized for Slack. Supports per-thread session isolation.",
+      inputSchema: {
+        query: z
+          .string()
+          .min(1)
+          .describe("The slack query to send to the agent"),
+        systemPrompt: z
+          .string()
+          .optional()
+          .describe("Optional additional system prompt to prepend"),
+        threadId: z
+          .string()
+          .optional()
+          .describe("Slack thread identifier for session isolation"),
+      },
+    },
+    async ({ query, systemPrompt, threadId }) => {
+      const existingSessionId = threadId
+        ? context.threadSessions.get(threadId)
+        : undefined
+
+      const existingConnectedServers = existingSessionId
+        ? context.sessionConnectedServers.get(existingSessionId)
+        : undefined
+
+      const { response, connectedServers } = await runStandaloneAgentLoop({
+        prompt: query,
+        mcpServer,
+        sessionId: existingSessionId,
+        additionalSystemPrompt: systemPrompt,
+        existingConnectedServers,
+        onSessionIdReceived: (newSessionId) => {
+          if (threadId) {
+            context.threadSessions.set(threadId, newSessionId)
+          }
+        },
+      })
+
+      // Update the session's connected servers
+      if (existingSessionId || threadId) {
+        const sessionId =
+          existingSessionId || context.threadSessions.get(threadId!)
+        if (sessionId) {
+          context.sessionConnectedServers.set(sessionId, connectedServers)
+        }
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: response,
+          },
+        ],
+      }
+    }
+  )
+}
diff --git a/src/mcp/tools/getAgentStatus.ts b/src/mcp/tools/getAgentStatus.ts
