Ultra MCP

Instructions

Implementation Reference

• src/handlers/ultra-tools.ts:290-354 (handler)

  Core handler function that implements the ultra-session tool logic, handling create, list, get, archive, and delete actions for conversation sessions using conversationMemory.

  export async function handleSession(args: any) {
    const { action, sessionId, name, status = 'active' } = args;
  
    switch (action) {
      case 'create': {
        const session = await conversationMemory.getOrCreateSession(sessionId, name);
        return {
          content: [
            {
              type: 'text',
              text: `## Session Created\n\nID: ${session.id}\nName: ${session.name || 'Unnamed'}\nStatus: ${session.status}\nCreated: ${session.createdAt}`
            }
          ]
        };
      }
  
      case 'list': {
        const sessionsResult = await conversationMemory.listSessions(status, 20);
        const sessionList = sessionsResult.sessions.map((s: any) => 
          `- **${s.name || s.id}** (${s.id})\n  Messages: ${s.messageCount}, Files: ${s.fileCount}, Tokens: ${s.totalTokens}, Cost: $${s.totalCost.toFixed(4)}\n  Last Activity: ${s.lastActivity.toISOString()}`
        ).join('\n\n');
  
        return {
          content: [
            {
              type: 'text',
              text: `## Sessions (${status})\n\n${sessionList || 'No sessions found.'}`
            }
          ]
        };
      }
  
      case 'get': {
        if (!sessionId) throw new Error('Session ID required for get action');
        const context = await conversationMemory.getConversationContext(sessionId, undefined, true);
        
        return {
          content: [
            {
              type: 'text',
              text: `## Session Details\n\nID: ${sessionId}\nMessages: ${context.messages.length}\nFiles: ${context.files.length}\nTotal Tokens: ${context.totalTokens}\nTotal Cost: $${context.totalCost.toFixed(4)}\n\nBudget:\n- Max Tokens: ${context.budget?.maxTokens || 'None'}\n- Max Cost: $${context.budget?.maxCostUsd || 'None'}\n- Used Tokens: ${context.budget?.usedTokens || 0}\n- Used Cost: $${context.budget?.usedCostUsd || 0}`
            }
          ]
        };
      }
  
      case 'archive':
      case 'delete': {
        if (!sessionId) throw new Error(`Session ID required for ${action} action`);
        await conversationMemory.updateSessionStatus(sessionId, action === 'archive' ? 'archived' : 'deleted');
        
        return {
          content: [
            {
              type: 'text',
              text: `## Session ${action === 'archive' ? 'Archived' : 'Deleted'}\n\nSession ${sessionId} has been ${action === 'archive' ? 'archived' : 'deleted'}.`
            }
          ]
        };
      }
  
      default:
        throw new Error(`Unknown action: ${action}`);
    }
  }

• src/server.ts:163-168 (schema)

  Zod schema defining the input parameters for the ultra-session tool: action, sessionId, name, status.

  const ZenSessionSchema = z.object({
    action: z.enum(["create", "list", "get", "archive", "delete"]).describe("Action to perform"),
    sessionId: z.string().optional().describe("Session ID (required for get, archive, delete actions)"),
    name: z.string().optional().describe("Session name (optional for create action)"),
    status: z.enum(["active", "archived", "deleted"]).optional().describe("Session status filter for list action (default: active)"),
  });

• src/server.ts:986-992 (registration)

  Registers the ultra-session tool with MCP server, providing title, description, input schema, and handler function.

  server.registerTool("ultra-session", {
    title: "Zen Session",
    description: "Manage conversation sessions for persistent context and memory",
    inputSchema: ZenSessionSchema.shape,
  }, async (args) => {
    return await handleSession(args) as any;
  });