ShadowGit MCP Server

Instructions

Implementation Reference

• src/handlers/session-handler.ts:78-112 (handler)

  Main handler function that executes the end_session tool: validates input, calls SessionClient to end the session via API, and formats the MCP response.

    async endSession(args: unknown): Promise<MCPToolResponse> {
      // Validate args
      if (!this.isEndSessionArgs(args)) {
        return createErrorResponse(
          'Error: "sessionId" is required for end_session.'
        );
      }
  
      // End session
      const success = await this.sessionClient.endSession(
        args.sessionId,
        args.commitHash
      );
  
      if (success) {
        log('info', `Session ended: ${args.sessionId}`);
        return {
          content: [{
            type: 'text',
            text: `Session ${args.sessionId} ended successfully.`
          }]
        };
      }
  
      return createErrorResponse(
        `❌ **Failed to End Session**
  ${'='.repeat(50)}
  
  ⚠️ The session may have already ended or expired.
  
  **Note:** Auto-commits may have already resumed.
  
  💡 **NEXT STEP:** You can continue working or start a new session.`
      );
    }

• src/shadowgit-mcp-server.ts:142-158 (schema)

  MCP protocol input schema definition for the end_session tool, specifying required sessionId and optional commitHash.

    name: 'end_session',
    description: 'End your work session to resume ShadowGit auto-commits. MUST be called AFTER checkpoint to properly close your work session.',
    inputSchema: {
      type: 'object',
      properties: {
        sessionId: {
          type: 'string',
          description: 'Session ID from start_session',
        },
        commitHash: {
          type: 'string',
          description: 'Commit hash from checkpoint (optional)',
        },
      },
      required: ['sessionId'],
    },
  }

• src/shadowgit-mcp-server.ts:182-184 (registration)

  Registration in the tool dispatch switch statement, routing end_session calls to the SessionHandler.

  case 'end_session':
    return await this.sessionHandler.endSession(args);

• src/core/session-client.ts:64-100 (helper)

  Core helper method that performs the HTTP POST to the Session API endpoint /session/end to actually end the session.

  async endSession(sessionId: string, commitHash?: string): Promise<boolean> {
    try {
      const controller = new AbortController();
      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
  
      const data: SessionEndRequest = { sessionId };
      if (commitHash) {
        data.commitHash = commitHash;
      }
  
      const response = await fetch(`${this.baseUrl}/session/end`, {
        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 SessionEndResponse;
        if (result.success) {
          log('info', `Session ended: ${sessionId}`);
          return true;
        }
      }
      
      log('warn', `Failed to end session: ${response.status} ${response.statusText}`);
    } catch (error) {
      if (error instanceof Error && error.name !== 'AbortError') {
        log('debug', `Failed to end session: ${error.message}`);
      }
    }
    return false;
  }

• src/handlers/session-handler.ts:125-132 (schema)

  TypeScript interface and runtime validator for end_session arguments in the handler.

  private isEndSessionArgs(args: unknown): args is EndSessionArgs {
    return (
      typeof args === 'object' &&
      args !== null &&
      'sessionId' in args &&
      typeof (args as EndSessionArgs).sessionId === 'string'
    );
  }