@poolzin/pool-bot 2026.4.32 → 2026.4.34

package/dist/mcp/server.js

@@ -0,0 +1,463 @@
+/**
+ * MCP (Model Context Protocol) Server for PoolBot.
+ *
+ * Exposes PoolBot sessions and conversations to MCP-compatible clients
+ * like Claude Desktop, Cursor, VS Code, etc.
+ *
+ * Supports both stdio and Streamable HTTP transports.
+ *
+ * @see https://modelcontextprotocol.io/
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createServer } from "node:http";
+import { parse as parseUrl } from "node:url";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig } from "../config/config.js";
+import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
+// ── Session Database Helpers ─────────────────────────────────────────
+function getSessionStorePath(workspaceDir, agentId) {
+    return join(workspaceDir, "memory", agentId, "sessions.json");
+}
+function loadSessions(workspaceDir, agentId) {
+    const storePath = getSessionStorePath(workspaceDir, agentId);
+    if (!existsSync(storePath)) {
+        return [];
+    }
+    try {
+        const content = readFileSync(storePath, "utf-8");
+        const store = JSON.parse(content);
+        return Object.entries(store.sessions || {})
+            .map(([key, value]) => {
+            const session = value;
+            return {
+                sessionId: session.sessionId || key,
+                sessionKey: key,
+                createdAt: session.createdAt || 0,
+                updatedAt: session.updatedAt || 0,
+                messageCount: session.messageCount || 0,
+                model: session.model,
+            };
+        })
+            .sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    catch {
+        return [];
+    }
+}
+function getSessionMessagesPath(workspaceDir, agentId, sessionKey) {
+    return join(workspaceDir, "memory", agentId, "sessions", `${sessionKey}.jsonl`);
+}
+function loadSessionMessages(workspaceDir, agentId, sessionKey) {
+    const messagesPath = getSessionMessagesPath(workspaceDir, agentId, sessionKey);
+    if (!existsSync(messagesPath)) {
+        return [];
+    }
+    const messages = [];
+    const content = readFileSync(messagesPath, "utf-8");
+    const lines = content.trim().split("\n").filter(Boolean);
+    for (const line of lines) {
+        try {
+            const entry = JSON.parse(line);
+            if (entry.role === "user" || entry.role === "assistant" || entry.role === "system") {
+                messages.push({
+                    role: entry.role,
+                    content: entry.content || entry.message || "",
+                    timestamp: entry.timestamp || entry.createdAt || 0,
+                    toolCalls: entry.toolCalls || entry.tools,
+                });
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return messages;
+}
+function searchSessions(workspaceDir, agentId, query, limit = 10) {
+    const sessions = loadSessions(workspaceDir, agentId);
+    const results = [];
+    const queryLower = query.toLowerCase();
+    for (const session of sessions.slice(0, 50)) { // Limit search to recent 50 sessions
+        const messages = loadSessionMessages(workspaceDir, agentId, session.sessionKey);
+        const matches = [];
+        for (const msg of messages) {
+            if (msg.content.toLowerCase().includes(queryLower)) {
+                // Extract context around the match
+                const idx = msg.content.toLowerCase().indexOf(queryLower);
+                const start = Math.max(0, idx - 50);
+                const end = Math.min(msg.content.length, idx + query.length + 50);
+                const excerpt = msg.content.substring(start, end).replace(/\n/g, " ").trim();
+                matches.push(`[${msg.role}] ${excerpt}...`);
+                if (matches.length >= 3)
+                    break; // Max 3 matches per session
+            }
+        }
+        if (matches.length > 0) {
+            results.push({ session, matches });
+        }
+        if (results.length >= limit)
+            break;
+    }
+    return results;
+}
+// ── MCP Server Implementation ────────────────────────────────────────
+export class PoolBotMCPServer {
+    server;
+    options;
+    workspaceDir;
+    agentId;
+    constructor(options = {}) {
+        this.options = {
+            httpPort: 3000,
+            readOnly: false,
+            ...options,
+        };
+        const config = loadConfig();
+        this.agentId = options.agentId || resolveDefaultAgentId(config);
+        this.workspaceDir = options.workspaceDir || resolveAgentWorkspaceDir(config, this.agentId);
+        this.server = new Server({
+            name: "poolbot-mcp",
+            version: "1.0.0",
+        }, {
+            capabilities: {
+                tools: {},
+                resources: {},
+            },
+        });
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        // List available tools
+        this.server.setRequestHandler(ListToolsRequestSchema, () => {
+            const tools = [
+                {
+                    name: "list_sessions",
+                    description: "List all PoolBot sessions with metadata",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            limit: {
+                                type: "number",
+                                description: "Maximum number of sessions to return (default: 20)",
+                                default: 20,
+                            },
+                        },
+                    },
+                },
+                {
+                    name: "get_session",
+                    description: "Get details of a specific PoolBot session",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            sessionKey: {
+                                type: "string",
+                                description: "Session key or ID",
+                            },
+                        },
+                        required: ["sessionKey"],
+                    },
+                },
+                {
+                    name: "get_messages",
+                    description: "Get messages from a PoolBot session",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            sessionKey: {
+                                type: "string",
+                                description: "Session key or ID",
+                            },
+                            limit: {
+                                type: "number",
+                                description: "Maximum messages to return (default: 50)",
+                                default: 50,
+                            },
+                            role: {
+                                type: "string",
+                                description: "Filter by role: user, assistant, or system",
+                                enum: ["user", "assistant", "system"],
+                            },
+                        },
+                        required: ["sessionKey"],
+                    },
+                },
+                {
+                    name: "search_sessions",
+                    description: "Search across all PoolBot sessions for text",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            query: {
+                                type: "string",
+                                description: "Search query",
+                            },
+                            limit: {
+                                type: "number",
+                                description: "Maximum results to return (default: 10)",
+                                default: 10,
+                            },
+                        },
+                        required: ["query"],
+                    },
+                },
+                {
+                    name: "get_session_stats",
+                    description: "Get statistics about PoolBot sessions",
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                    },
+                },
+            ];
+            if (!this.options.readOnly) {
+                tools.push({
+                    name: "send_message",
+                    description: "Send a message to a PoolBot session",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            sessionKey: { type: "string", description: "Session key or ID" },
+                            message: { type: "string", description: "Message to send" },
+                        },
+                        required: ["sessionKey", "message"],
+                    },
+                });
+            }
+            return { tools };
+        });
+        // List available resources
+        this.server.setRequestHandler(ListResourcesRequestSchema, () => {
+            const sessions = loadSessions(this.workspaceDir, this.agentId);
+            const resources = sessions.slice(0, 100).map((session) => ({
+                uri: `poolbot://session/${session.sessionKey}`,
+                name: `Session ${session.sessionKey.substring(0, 8)}...`,
+                description: `${session.messageCount} messages, last updated ${new Date(session.updatedAt).toISOString()}`,
+                mimeType: "application/json",
+            }));
+            return { resources };
+        });
+        // Read resource content
+        this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+            const uri = request.params.uri;
+            const parsed = parseUrl(uri);
+            if (parsed.protocol === "poolbot:" && parsed.pathname?.startsWith("/session/")) {
+                const sessionKey = parsed.pathname.replace("/session/", "");
+                const messages = loadSessionMessages(this.workspaceDir, this.agentId, sessionKey);
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: "application/json",
+                            text: JSON.stringify(messages, null, 2),
+                        },
+                    ],
+                };
+            }
+            throw new Error(`Unknown resource: ${uri}`);
+        });
+        // Handle tool calls
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            try {
+                switch (name) {
+                    case "list_sessions": {
+                        const limit = args?.limit || 20;
+                        const sessions = loadSessions(this.workspaceDir, this.agentId).slice(0, limit);
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify(sessions, null, 2),
+                                },
+                            ],
+                        };
+                    }
+                    case "get_session": {
+                        const sessionKey = args?.sessionKey;
+                        if (!sessionKey) {
+                            throw new Error("sessionKey is required");
+                        }
+                        const sessions = loadSessions(this.workspaceDir, this.agentId);
+                        const session = sessions.find((s) => s.sessionKey === sessionKey || s.sessionId === sessionKey);
+                        if (!session) {
+                            throw new Error(`Session not found: ${sessionKey}`);
+                        }
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify(session, null, 2),
+                                },
+                            ],
+                        };
+                    }
+                    case "get_messages": {
+                        const sessionKey = args?.sessionKey;
+                        const limit = args?.limit || 50;
+                        const role = args?.role;
+                        if (!sessionKey) {
+                            throw new Error("sessionKey is required");
+                        }
+                        let messages = loadSessionMessages(this.workspaceDir, this.agentId, sessionKey);
+                        if (role) {
+                            messages = messages.filter((m) => m.role === role);
+                        }
+                        messages = messages.slice(-limit);
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify(messages, null, 2),
+                                },
+                            ],
+                        };
+                    }
+                    case "search_sessions": {
+                        const query = args?.query;
+                        const limit = args?.limit || 10;
+                        if (!query) {
+                            throw new Error("query is required");
+                        }
+                        const results = searchSessions(this.workspaceDir, this.agentId, query, limit);
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify(results, null, 2),
+                                },
+                            ],
+                        };
+                    }
+                    case "get_session_stats": {
+                        const sessions = loadSessions(this.workspaceDir, this.agentId);
+                        const totalMessages = sessions.reduce((sum, s) => sum + s.messageCount, 0);
+                        const now = Date.now();
+                        const last24h = sessions.filter((s) => now - s.updatedAt < 24 * 60 * 60 * 1000).length;
+                        const last7d = sessions.filter((s) => now - s.updatedAt < 7 * 24 * 60 * 60 * 1000).length;
+                        const stats = {
+                            totalSessions: sessions.length,
+                            totalMessages,
+                            sessionsLast24h: last24h,
+                            sessionsLast7d: last7d,
+                            oldestSession: sessions.length > 0 ? new Date(sessions[sessions.length - 1].createdAt).toISOString() : null,
+                            newestSession: sessions.length > 0 ? new Date(sessions[0].updatedAt).toISOString() : null,
+                        };
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify(stats, null, 2),
+                                },
+                            ],
+                        };
+                    }
+                    case "send_message": {
+                        if (this.options.readOnly) {
+                            throw new Error("Server is in read-only mode");
+                        }
+                        const sessionKey = args?.sessionKey;
+                        const message = args?.message;
+                        if (!sessionKey || !message) {
+                            throw new Error("sessionKey and message are required");
+                        }
+                        // Note: This would need integration with the actual gateway to send messages
+                        // For now, return a placeholder response
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Message sent to session ${sessionKey}. Note: Full integration requires gateway connection.`,
+                                },
+                            ],
+                        };
+                    }
+                    default:
+                        throw new Error(`Unknown tool: ${name}`);
+                }
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+    }
+    /**
+     * Start MCP server with stdio transport (for Claude Desktop, etc.)
+     */
+    async startStdio() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error("PoolBot MCP Server running on stdio");
+    }
+    /**
+     * Start MCP server with HTTP transport (for web clients)
+     */
+    async startHTTP(port) {
+        const httpPort = port || this.options.httpPort || 3000;
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => crypto.randomUUID(),
+        });
+        await this.server.connect(transport);
+        const server = createServer(async (req, res) => {
+            if (req.url === "/mcp") {
+                await transport.handleRequest(req, res);
+            }
+            else {
+                res.writeHead(404);
+                res.end("Not found");
+            }
+        });
+        await new Promise((resolve) => {
+            server.listen(httpPort, () => {
+                console.error(`PoolBot MCP Server running on http://localhost:${httpPort}/mcp`);
+                resolve();
+            });
+        });
+    }
+    /**
+     * Stop the MCP server
+     */
+    async stop() {
+        await this.server.close();
+    }
+}
+// ── CLI Entry Point ──────────────────────────────────────────────────
+export async function runMCPServer(options = {}) {
+    const server = new PoolBotMCPServer(options);
+    const args = process.argv.slice(2);
+    const httpPort = args.find((arg) => arg.startsWith("--port="))?.split("=")[1];
+    const isHTTP = args.includes("--http") || !!httpPort;
+    try {
+        if (isHTTP) {
+            await server.startHTTP(httpPort ? parseInt(httpPort, 10) : undefined);
+        }
+        else {
+            await server.startStdio();
+        }
+        // Handle shutdown gracefully
+        process.on("SIGINT", async () => {
+            await server.stop();
+            process.exit(0);
+        });
+        process.on("SIGTERM", async () => {
+            await server.stop();
+            process.exit(0);
+        });
+    }
+    catch (error) {
+        console.error("Failed to start MCP server:", error);
+        process.exit(1);
+    }
+}

package/docs/mcp-server.md

@@ -0,0 +1,171 @@
+# PoolBot MCP Server
+
+## Overview
+
+The PoolBot MCP (Model Context Protocol) Server exposes your PoolBot sessions and conversations to MCP-compatible clients like:
+
+- **Claude Desktop** - Chat directly with your PoolBot session history
+- **Cursor** - Search and reference PoolBot conversations in your IDE
+- **VS Code** - Access PoolBot context from your editor
+- **Any MCP Client** - Standard protocol support
+
+## Features
+
+### Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_sessions` | List all PoolBot sessions with metadata |
+| `get_session` | Get details of a specific session |
+| `get_messages` | Get messages from a session (with optional role filter) |
+| `search_sessions` | Search across all sessions for text |
+| `get_session_stats` | Get statistics about your sessions |
+| `send_message` | Send a message to a session (optional, read-only mode disables this) |
+
+### Resources
+
+Sessions are exposed as MCP resources at URIs like:
+```
+poolbot://session/<sessionKey>
+```
+
+## Installation
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "poolbot": {
+      "command": "poolbot",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+### Cursor / VS Code
+
+Add to your MCP settings:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "poolbot": {
+        "command": "poolbot",
+        "args": ["mcp", "serve"]
+      }
+    }
+  }
+}
+```
+
+## Usage
+
+### Start MCP Server (stdio mode)
+
+```bash
+poolbot mcp serve
+```
+
+This is the default mode for Claude Desktop and most MCP clients.
+
+### Start MCP Server (HTTP mode)
+
+```bash
+poolbot mcp serve --http
+poolbot mcp serve --http --port 3001
+```
+
+HTTP mode is useful for web-based MCP clients or remote access.
+
+### Read-Only Mode
+
+```bash
+poolbot mcp serve --read-only
+```
+
+Disables the `send_message` tool for security.
+
+## Examples
+
+### List Sessions
+
+```json
+{
+  "name": "list_sessions",
+  "arguments": {
+    "limit": 20
+  }
+}
+```
+
+### Search Sessions
+
+```json
+{
+  "name": "search_sessions",
+  "arguments": {
+    "query": "deployment configuration",
+    "limit": 10
+  }
+}
+```
+
+### Get Messages
+
+```json
+{
+  "name": "get_messages",
+  "arguments": {
+    "sessionKey": "abc123...",
+    "limit": 50,
+    "role": "assistant"
+  }
+}
+```
+
+## Security
+
+- MCP server runs locally by default
+- No external network access required for stdio mode
+- HTTP mode binds to localhost by default
+- Use `--read-only` to disable message sending
+- Sessions are read from your local PoolBot workspace
+
+## Troubleshooting
+
+### "Command not found: poolbot"
+
+Ensure PoolBot is installed globally:
+```bash
+npm install -g @poolzin/pool-bot
+```
+
+### "No sessions found"
+
+Sessions are loaded from your PoolBot workspace. Ensure you have existing sessions in `~/.poolbot/memory/<agentId>/sessions/`.
+
+### HTTP mode not connecting
+
+Ensure the port is not in use:
+```bash
+poolbot mcp serve --http --port 3001
+```
+
+## Architecture
+
+The MCP server:
+1. Reads sessions from PoolBot's session store (`sessions.json`)
+2. Loads messages from JSONL files (`sessions/<sessionKey>.jsonl`)
+3. Exposes tools and resources via the MCP protocol
+4. Supports both stdio (for local clients) and HTTP transports
+
+## See Also
+
+- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
+- [Claude Desktop MCP Setup](https://claude.ai/mcp)
+- [PoolBot Documentation](/docs/)