Skip to main content
Glama
MUSE-CODE-SPACE

Vibe Coding Documentation MCP (MUSE)

by MUSE-CODE-SPACE
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

muse_session_history

Manage vibe coding session history by saving, retrieving, searching, and updating sessions with code contexts and design decisions.

Instructions

Manages vibe coding session history. Save, retrieve, search, and manage past coding sessions with their code contexts and design decisions.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
actionYesAction to perform: save (create new), get (retrieve by ID), update (modify existing), delete (remove), list (get all), search (find by keyword), stats (storage statistics)
sessionIdNoSession ID (required for get, update, delete actions)
titleNoSession title (required for save, optional for update)
summaryNoSession summary (required for save, optional for update)
tagsNoTags for categorization
codeContextsNoArray of code context objects
designDecisionsNoArray of design decision objects
metadataNoAdditional metadata
limitNoMaximum results to return (for list/search, default: 50)
offsetNoNumber of results to skip (for list, default: 0)
filterTagsNoFilter by tags (for list)
sortByNoSort field (for list, default: updatedAt)
sortOrderNoSort order (for list, default: desc)
keywordNoSearch keyword (required for search action)
searchInNoFields to search in (for search, default: all)

Implementation Reference

  • src/tools/sessionHistory.ts:65-240 (handler)
    Main handler for the muse_session_history tool. Dispatches to different actions: save, get, update, delete, list, search, stats. Uses sessionStorage core module for persistence.
    export async function sessionHistoryTool(input: SessionHistoryInput): Promise<SessionHistoryOutput> {
  const { action } = input;

  try {
    switch (action) {
      case 'save': {
        if (!input.title || !input.summary) {
          return {
            success: false,
            action,
            error: 'title and summary are required for save action'
          };
        }

        const session = await saveSession({
          title: input.title,
          summary: input.summary,
          tags: input.tags || [],
          codeContexts: input.codeContexts || [],
          designDecisions: input.designDecisions || [],
          metadata: input.metadata
        });

        return {
          success: true,
          action,
          session,
          message: `Session saved: ${session.id}`
        };
      }

      case 'get': {
        if (!input.sessionId) {
          return {
            success: false,
            action,
            error: 'sessionId is required for get action'
          };
        }

        const session = await getSession(input.sessionId);
        if (!session) {
          return {
            success: false,
            action,
            error: `Session not found: ${input.sessionId}`
          };
        }

        return {
          success: true,
          action,
          session,
          message: `Session retrieved: ${session.title}`
        };
      }

      case 'update': {
        if (!input.sessionId) {
          return {
            success: false,
            action,
            error: 'sessionId is required for update action'
          };
        }

        const updates: Partial<SessionData> = {};
        if (input.title !== undefined) updates.title = input.title;
        if (input.summary !== undefined) updates.summary = input.summary;
        if (input.tags !== undefined) updates.tags = input.tags;
        if (input.codeContexts !== undefined) updates.codeContexts = input.codeContexts;
        if (input.designDecisions !== undefined) updates.designDecisions = input.designDecisions;
        if (input.metadata !== undefined) updates.metadata = input.metadata;

        const session = await updateSession(input.sessionId, updates);

        return {
          success: true,
          action,
          session,
          message: `Session updated: ${session.id}`
        };
      }

      case 'delete': {
        if (!input.sessionId) {
          return {
            success: false,
            action,
            error: 'sessionId is required for delete action'
          };
        }

        const deleted = await deleteSession(input.sessionId);
        if (!deleted) {
          return {
            success: false,
            action,
            error: `Session not found: ${input.sessionId}`
          };
        }

        return {
          success: true,
          action,
          message: `Session deleted: ${input.sessionId}`
        };
      }

      case 'list': {
        const { sessions, total } = await listSessions({
          limit: input.limit,
          offset: input.offset,
          tags: input.filterTags,
          sortBy: input.sortBy,
          sortOrder: input.sortOrder
        });

        return {
          success: true,
          action,
          sessions,
          total,
          message: `Found ${total} session(s)`
        };
      }

      case 'search': {
        if (!input.keyword) {
          return {
            success: false,
            action,
            error: 'keyword is required for search action'
          };
        }

        const sessions = await searchSessions(input.keyword, {
          limit: input.limit,
          searchIn: input.searchIn
        });

        return {
          success: true,
          action,
          sessions,
          total: sessions.length,
          message: `Found ${sessions.length} session(s) matching "${input.keyword}"`
        };
      }

      case 'stats': {
        const stats = await getStorageStats();

        return {
          success: true,
          action,
          stats,
          message: `Storage contains ${stats.totalSessions} session(s)`
        };
      }

      default:
        return {
          success: false,
          action,
          error: `Unknown action: ${action}`
        };
    }
  } catch (error) {
    return {
      success: false,
      action,
      error: error instanceof Error ? error.message : String(error)
    };
  }
}
  • src/stdio.ts:89-92 (handler)
    Stdio handler that validates input via SessionHistorySchema and delegates to sessionHistoryTool.
    muse_session_history: async (args: unknown) => {
  const validated = validateInput(SessionHistorySchema, args);
  return sessionHistoryTool(validated as Parameters<typeof sessionHistoryTool>[0]);
},
  • src/tools/sessionHistory.ts:242-317 (schema)
    MCP schema definition for the muse_session_history tool, including name, description, and inputSchema with all properties (action, sessionId, title, summary, tags, etc.).
    export const sessionHistorySchema = {
  name: 'muse_session_history',
  description: 'Manages vibe coding session history. Save, retrieve, search, and manage past coding sessions with their code contexts and design decisions.',
  inputSchema: {
    type: 'object',
    properties: {
      action: {
        type: 'string',
        enum: ['save', 'get', 'update', 'delete', 'list', 'search', 'stats'],
        description: 'Action to perform: save (create new), get (retrieve by ID), update (modify existing), delete (remove), list (get all), search (find by keyword), stats (storage statistics)'
      },
      sessionId: {
        type: 'string',
        description: 'Session ID (required for get, update, delete actions)'
      },
      title: {
        type: 'string',
        description: 'Session title (required for save, optional for update)'
      },
      summary: {
        type: 'string',
        description: 'Session summary (required for save, optional for update)'
      },
      tags: {
        type: 'array',
        items: { type: 'string' },
        description: 'Tags for categorization'
      },
      codeContexts: {
        type: 'array',
        description: 'Array of code context objects'
      },
      designDecisions: {
        type: 'array',
        description: 'Array of design decision objects'
      },
      metadata: {
        type: 'object',
        description: 'Additional metadata'
      },
      limit: {
        type: 'number',
        description: 'Maximum results to return (for list/search, default: 50)'
      },
      offset: {
        type: 'number',
        description: 'Number of results to skip (for list, default: 0)'
      },
      filterTags: {
        type: 'array',
        items: { type: 'string' },
        description: 'Filter by tags (for list)'
      },
      sortBy: {
        type: 'string',
        enum: ['createdAt', 'updatedAt', 'title'],
        description: 'Sort field (for list, default: updatedAt)'
      },
      sortOrder: {
        type: 'string',
        enum: ['asc', 'desc'],
        description: 'Sort order (for list, default: desc)'
      },
      keyword: {
        type: 'string',
        description: 'Search keyword (required for search action)'
      },
      searchIn: {
        type: 'array',
        items: { type: 'string', enum: ['title', 'summary', 'tags'] },
        description: 'Fields to search in (for search, default: all)'
      }
    },
    required: ['action']
  }
};
  • src/core/schemas.ts:199-231 (schema)
    Zod validation schema for session history input. Defines all fields with proper types and validations used by the stdio handler.
    export const SessionHistorySchema = z.object({
  action: z.enum(['save', 'get', 'update', 'delete', 'list', 'search', 'stats']),
  sessionId: z.string().optional(),
  title: z.string().optional(),
  summary: z.string().optional(),
  tags: z.array(z.string()).optional(),
  codeContexts: z.array(z.object({
    sessionId: z.string(),
    timestamp: z.string(),
    codeBlocks: z.array(z.object({
      language: z.string(),
      code: z.string(),
      filename: z.string().optional()
    })),
    conversationSummary: z.string()
  })).optional(),
  designDecisions: z.array(z.object({
    id: z.string(),
    title: z.string(),
    description: z.string(),
    rationale: z.string(),
    category: z.string(),
    timestamp: z.string()
  })).optional(),
  metadata: z.record(z.unknown()).optional(),
  limit: z.number().optional(),
  offset: z.number().optional(),
  filterTags: z.array(z.string()).optional(),
  sortBy: z.enum(['createdAt', 'updatedAt', 'title']).optional(),
  sortOrder: z.enum(['asc', 'desc']).optional(),
  keyword: z.string().optional(),
  searchIn: z.array(z.enum(['title', 'summary', 'tags'])).optional()
});
  • src/core/sessionStorage.ts:1-310 (helper)
    Core session storage module. Persists sessions as JSON files. Supports CRUD operations, listing with filtering/sorting/pagination, keyword search across title/summary/tags, and storage statistics.
    /**
 * 세션 스토리지 모듈
 * 바이브 코딩 세션을 저장하고 조회하는 기능 제공
 * v2.6: 세션 히스토리 기능
 */

import { promises as fs } from 'fs';
import * as path from 'path';
import { logger } from './logger.js';

const storageLogger = logger.child({ module: 'sessionStorage' });

export interface StoredSession {
  id: string;
  title: string;
  summary: string;
  createdAt: string;
  updatedAt: string;
  tags: string[];
  codeContextCount: number;
  designDecisionCount: number;
  metadata?: Record<string, unknown>;
}

export interface SessionData {
  id: string;
  title: string;
  summary: string;
  createdAt: string;
  updatedAt: string;
  tags: string[];
  codeContexts: Array<{
    sessionId: string;
    timestamp: string;
    codeBlocks: Array<{ language: string; code: string; filename?: string }>;
    conversationSummary: string;
  }>;
  designDecisions: Array<{
    id: string;
    title: string;
    description: string;
    rationale: string;
    category: string;
    timestamp: string;
  }>;
  metadata?: Record<string, unknown>;
}

// Default storage path
const DEFAULT_STORAGE_DIR = process.env.VIBE_CODING_STORAGE_DIR ||
  path.join(process.env.HOME || process.env.USERPROFILE || '.', '.vibe-coding-mcp', 'sessions');

let storageDir = DEFAULT_STORAGE_DIR;

/**
 * Initialize storage directory
 */
export async function initializeStorage(customDir?: string): Promise<void> {
  if (customDir) {
    storageDir = customDir;
  }

  try {
    await fs.mkdir(storageDir, { recursive: true });
    storageLogger.info('Storage initialized', { path: storageDir });
  } catch (error) {
    storageLogger.error('Failed to initialize storage', error as Error);
    throw error;
  }
}

/**
 * Generate unique session ID
 */
function generateSessionId(): string {
  const timestamp = Date.now().toString(36);
  const random = Math.random().toString(36).substring(2, 8);
  return `session_${timestamp}_${random}`;
}

/**
 * Get session file path
 */
function getSessionPath(sessionId: string): string {
  return path.join(storageDir, `${sessionId}.json`);
}

/**
 * Save a session
 */
export async function saveSession(data: Omit<SessionData, 'id' | 'createdAt' | 'updatedAt'>): Promise<SessionData> {
  await initializeStorage();

  const sessionId = generateSessionId();
  const now = new Date().toISOString();

  const session: SessionData = {
    id: sessionId,
    createdAt: now,
    updatedAt: now,
    ...data
  };

  const filePath = getSessionPath(sessionId);

  try {
    await fs.writeFile(filePath, JSON.stringify(session, null, 2), 'utf-8');
    storageLogger.info('Session saved', { sessionId, title: session.title });
    return session;
  } catch (error) {
    storageLogger.error('Failed to save session', error as Error);
    throw error;
  }
}

/**
 * Update an existing session
 */
export async function updateSession(sessionId: string, updates: Partial<Omit<SessionData, 'id' | 'createdAt'>>): Promise<SessionData> {
  const existing = await getSession(sessionId);
  if (!existing) {
    throw new Error(`Session not found: ${sessionId}`);
  }

  const updated: SessionData = {
    ...existing,
    ...updates,
    updatedAt: new Date().toISOString()
  };

  const filePath = getSessionPath(sessionId);

  try {
    await fs.writeFile(filePath, JSON.stringify(updated, null, 2), 'utf-8');
    storageLogger.info('Session updated', { sessionId });
    return updated;
  } catch (error) {
    storageLogger.error('Failed to update session', error as Error);
    throw error;
  }
}

/**
 * Get a session by ID
 */
export async function getSession(sessionId: string): Promise<SessionData | null> {
  const filePath = getSessionPath(sessionId);

  try {
    const content = await fs.readFile(filePath, 'utf-8');
    return JSON.parse(content) as SessionData;
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
      return null;
    }
    storageLogger.error('Failed to read session', error as Error);
    throw error;
  }
}

/**
 * Delete a session
 */
export async function deleteSession(sessionId: string): Promise<boolean> {
  const filePath = getSessionPath(sessionId);

  try {
    await fs.unlink(filePath);
    storageLogger.info('Session deleted', { sessionId });
    return true;
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
      return false;
    }
    storageLogger.error('Failed to delete session', error as Error);
    throw error;
  }
}

/**
 * List all sessions (summary only)
 */
export async function listSessions(options?: {
  limit?: number;
  offset?: number;
  tags?: string[];
  sortBy?: 'createdAt' | 'updatedAt' | 'title';
  sortOrder?: 'asc' | 'desc';
}): Promise<{ sessions: StoredSession[]; total: number }> {
  await initializeStorage();

  const { limit = 50, offset = 0, tags, sortBy = 'updatedAt', sortOrder = 'desc' } = options || {};

  try {
    const files = await fs.readdir(storageDir);
    const sessionFiles = files.filter(f => f.endsWith('.json'));

    const sessions: StoredSession[] = [];

    for (const file of sessionFiles) {
      try {
        const content = await fs.readFile(path.join(storageDir, file), 'utf-8');
        const data = JSON.parse(content) as SessionData;

        // Filter by tags if specified
        if (tags && tags.length > 0) {
          const hasTag = tags.some(tag => data.tags?.includes(tag));
          if (!hasTag) continue;
        }

        sessions.push({
          id: data.id,
          title: data.title,
          summary: data.summary,
          createdAt: data.createdAt,
          updatedAt: data.updatedAt,
          tags: data.tags || [],
          codeContextCount: data.codeContexts?.length || 0,
          designDecisionCount: data.designDecisions?.length || 0,
          metadata: data.metadata
        });
      } catch {
        // Skip invalid files
        continue;
      }
    }

    // Sort
    sessions.sort((a, b) => {
      const aVal = a[sortBy] || '';
      const bVal = b[sortBy] || '';
      const cmp = aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
      return sortOrder === 'desc' ? -cmp : cmp;
    });

    // Paginate
    const total = sessions.length;
    const paginated = sessions.slice(offset, offset + limit);

    return { sessions: paginated, total };
  } catch (error) {
    storageLogger.error('Failed to list sessions', error as Error);
    throw error;
  }
}

/**
 * Search sessions by keyword
 */
export async function searchSessions(keyword: string, options?: {
  limit?: number;
  searchIn?: ('title' | 'summary' | 'tags')[];
}): Promise<StoredSession[]> {
  const { limit = 20, searchIn = ['title', 'summary', 'tags'] } = options || {};
  const lowerKeyword = keyword.toLowerCase();

  const { sessions } = await listSessions({ limit: 1000 });

  const matches = sessions.filter(session => {
    if (searchIn.includes('title') && session.title.toLowerCase().includes(lowerKeyword)) {
      return true;
    }
    if (searchIn.includes('summary') && session.summary.toLowerCase().includes(lowerKeyword)) {
      return true;
    }
    if (searchIn.includes('tags') && session.tags.some(t => t.toLowerCase().includes(lowerKeyword))) {
      return true;
    }
    return false;
  });

  return matches.slice(0, limit);
}

/**
 * Get storage statistics
 */
export async function getStorageStats(): Promise<{
  totalSessions: number;
  totalCodeContexts: number;
  totalDesignDecisions: number;
  storageDir: string;
  oldestSession?: string;
  newestSession?: string;
}> {
  const { sessions, total } = await listSessions({ limit: 1000 });

  let totalCodeContexts = 0;
  let totalDesignDecisions = 0;

  for (const session of sessions) {
    totalCodeContexts += session.codeContextCount;
    totalDesignDecisions += session.designDecisionCount;
  }

  // Sort by createdAt to find oldest/newest
  const sorted = [...sessions].sort((a, b) =>
    new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime()
  );

  return {
    totalSessions: total,
    totalCodeContexts,
    totalDesignDecisions,
    storageDir,
    oldestSession: sorted[0]?.createdAt,
    newestSession: sorted[sorted.length - 1]?.createdAt
  };
}

Tool Definition Quality

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as persistence behavior, side effects, or permission requirements. The word 'manages' is vague.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is clear and not overly verbose. It efficiently states the tool's purpose without unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 15 parameters, no output schema, and no annotations, the description is too brief. It does not explain return values or behavior for each action, leaving significant gaps for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all parameters have descriptions. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it manages vibe coding session history with save, retrieve, search, and manage actions. However, it does not differentiate from siblings like muse_session_stats, which also deal with sessions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like muse_create_session_log or muse_session_stats. The description is generic and does not specify prerequisites or context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/MUSE-CODE-SPACE/vibe-coding-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server