ShadowGit MCP Server

Instructions

Implementation Reference

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

  The primary handler function for the 'start_session' tool. Validates input arguments, resolves the repository path, initiates the session using SessionClient, and returns a formatted response with session ID and workflow instructions.

    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)

  TypeScript interface defining the expected input arguments for the start_session tool: repo (string) and description (string).

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

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

  Dispatch logic in the CallToolRequest handler that routes 'start_session' calls to the SessionHandler's startSession method.

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

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

  Tool registration in the ListToolsRequest handler, defining the name, description, and input schema for 'start_session'.

    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/core/session-client.ts:27-59 (helper)

  Supporting utility in SessionClient that makes the HTTP request to the ShadowGit Session API to start a session and returns the session ID.

  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;
  }