start_session

Instructions

Implementation Reference

• src/handlers/session-handler.ts:30-73 (handler)

  The main handler function for the 'start_session' tool. Validates args (repo and description), resolves the repo path, calls sessionClient.startSession(), and returns a success response with the session ID or an error.

    async startSession(args: unknown): Promise<MCPToolResponse> {
      // Validate args
      if (!this.isStartSessionArgs(args)) {
        return createErrorResponse(
          'Error: Both "repo" and "description" are required for start_session.'
        );
      }
  
      // Resolve repository
      const repoPath = this.repositoryManager.resolveRepoPath(args.repo);
      if (!repoPath) {
        return createErrorResponse(
          `Error: Repository '${args.repo}' not found. Use list_repos() to see available repositories.`
        );
      }
  
      // Start session
      const sessionId = await this.sessionClient.startSession({
        repoPath,
        aiTool: 'MCP Client',
        description: args.description
      });
  
      if (sessionId) {
        log('info', `Session started: ${sessionId}`);
        return {
          content: [{
            type: 'text',
            text: `Session started successfully.
  Session ID: ${sessionId}
  
  📋 **Your Workflow Checklist:**
  1. Make your changes
  2. Call checkpoint() to commit
  3. Call end_session() with this session ID`
          }]
        };
      }
  
      // Fallback if Session API is offline
      return createErrorResponse(
        'Session API is offline. Proceeding without session tracking.'
      );
    }

• src/handlers/session-handler.ts:11-14 (schema)

  The StartSessionArgs interface defining required input fields: repo (string) and description (string).

  interface StartSessionArgs {
    repo: string;
    description: string;
  }

• src/types.ts:32-42 (schema)

  The SessionStartRequest type sent to the Session API containing repoPath, aiTool, and description.

  export interface SessionStartRequest {
    repoPath: string;
    aiTool: string;
    description: string;
  }
  
  export interface SessionStartResponse {
    success: boolean;
    sessionId?: string;
    error?: string;
  }

• src/shadowgit-mcp-server.ts:97-114 (registration)

  Tool registration in the MCP server's ListToolsRequestSchema handler, defining the name 'start_session', description, and inputSchema (repo and description as required strings).

  {
    name: 'start_session',
    description: 'Start a work session. MUST be called BEFORE making any changes. Without this, ShadowGit will create fragmented auto-commits during your work!',
    inputSchema: {
      type: 'object',
      properties: {
        repo: {
          type: 'string',
          description: 'Repository name',
        },
        description: {
          type: 'string',
          description: 'What you plan to do in this session',
        },
      },
      required: ['repo', 'description'],
    },
  },

• src/shadowgit-mcp-server.ts:176-177 (registration)

  Routing in the CallToolRequestSchema handler: the 'start_session' case delegates to sessionHandler.startSession(args).

  case 'start_session':
    return await this.sessionHandler.startSession(args);

• src/core/session-client.ts:27-59 (helper)

  The HTTP client method that POSTs to the Session API's /session/start endpoint with SessionStartRequest data and returns the sessionId string or null on failure.

  async startSession(data: SessionStartRequest): Promise<string | null> {
    try {
      const controller = new AbortController();
      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
  
      const response = await fetch(`${this.baseUrl}/session/start`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(data),
        signal: controller.signal,
      });
  
      clearTimeout(timeoutId);
  
      if (response.ok) {
        const result = await response.json() as SessionStartResponse;
        if (result.success && result.sessionId) {
          log('info', `Session started: ${result.sessionId} for ${data.repoPath}`);
          return result.sessionId;
        }
      }
      
      log('warn', `Failed to start session: ${response.status} ${response.statusText}`);
    } catch (error) {
      // Silently fail - don't break MCP if Session API is down
      if (error instanceof Error && error.name !== 'AbortError') {
        log('debug', `Session API unavailable: ${error.message}`);
      }
    }
    return null;
  }

• src/handlers/session-handler.ts:114-123 (helper)

  Type guard isStartSessionArgs that validates the incoming args object has 'repo' and 'description' string properties.

  private isStartSessionArgs(args: unknown): args is StartSessionArgs {
    return (
      typeof args === 'object' &&
      args !== null &&
      'repo' in args &&
      'description' in args &&
      typeof (args as StartSessionArgs).repo === 'string' &&
      typeof (args as StartSessionArgs).description === 'string'
    );
  }