MCP Progress Notification System in Instagit: Real-Time Streaming Updates Explained

Instagit implements an MCP progress notification system that streams real-time status updates to clients every 250 milliseconds during AI analysis, using unique progress tokens to track concurrent requests.

Instagit operates as an MCP (Model-Context-Protocol) server, enabling AI assistants to query Git repositories through standardized tool calls. When clients invoke the ask_repo tool, Instagit leverages its MCP progress notification system to deliver live feedback during streaming responses, allowing clients to monitor token usage and processing status in real time.

How the MCP Progress Notification System Works

The system follows a structured protocol to maintain stateful communication between the Instagit server and MCP-compatible clients.

Progress Token Generation

Every tool invocation receives a unique identifier to distinguish concurrent operations. In src/index.ts, Instagit either reuses a client-provided token or generates a fresh one using a timestamp-based scheme.

// src/index.ts – generate or reuse progress token
const progressToken = extra._meta?.progressToken ?? `ask_repo_${Date.now()}`;

This token serves as the correlation ID for all subsequent notifications related to that specific request.

Sending Progress Notifications

Instagit transmits updates through the MCP channel using the standardized notifications/progress method. The sendProgress helper function in src/index.ts constructs payloads containing the token, current output token count, and human-readable status messages.

// src/index.ts – emit progress notification
const sendProgress = async (message: string) => {
  try {
    await extra.sendNotification({
      method: "notifications/progress" as const,
      params: {
        progressToken,
        progress: tracker.outputTokens,
        message,
      },
    });
  } catch {
    // client may not support progress – ignore errors
  }
};

The system gracefully handles clients that do not implement progress support by catching and ignoring transmission errors.

The Streaming Heartbeat

During active streaming operations in src/api.ts, a heartbeat mechanism triggers every 250 milliseconds to provide continuous feedback. This interval ensures clients receive frequent updates without overwhelming the communication channel.

// src/api.ts – heartbeat driving streaming updates
if (progressCallback) {
  heartbeatInterval = setInterval(async () => {
    if (!tracker.done) {
      try {
        await progressCallback(formatMessage(tracker));
      } catch {}
    }
  }, 250);
}

The heartbeat continues until the ProgressTracker marks the operation as complete, ensuring clients always know the processing status.

Key Components of the Progress System

Two specialized modules handle the state management and presentation of progress data.

ProgressTracker State Management

The ProgressTracker class maintains comprehensive metrics about the ongoing operation, including:

• Timing data: Start time and elapsed duration
• Token counts: Input and output token tallies
• Status flags: Completion state and error conditions

This state object updates continuously during streaming and serves as the single source of truth for progress calculations.

Message Formatting

The formatMessage function in src/kitt.ts transforms raw tracker data into concise, user-friendly status strings. It generates visual progress indicators using block characters and includes timing and token statistics.

// src/kitt.ts – format progress for display
export function formatMessage(
  tracker: import("./types.js").ProgressTracker,
  status?: string,
  tokens?: { input?: number; output?: number }
): string {
  // Returns formatted string like: "█░░· 3s · 150 tokens · Connecting…"
}

This formatting ensures that progress notifications remain readable across different client implementations while providing technical details for debugging.

Implementation Examples

Server-Side Progress Emission

When implementing the ask_repo tool handler, integrate progress notifications using the established pattern from src/index.ts:

const progressToken = extra._meta?.progressToken ?? `ask_repo_${Date.now()}`;

const sendProgress = async (message: string) => {
  await extra.sendNotification({
    method: "notifications/progress" as const,
    params: {
      progressToken,
      progress: tracker.outputTokens,
      message,
    },
  });
};

Client-Side Progress Handling

MCP clients receive progress notifications through event handlers. Implement a listener to update UI elements or log processing metrics:

client.on("notifications/progress", ({ progressToken, progress, message }) => {
  // Update progress bar or status indicator
  console.log(`[${progressToken}] ${message} (tokens: ${progress})`);
});

The progressToken parameter allows clients to route updates to the correct UI component when handling multiple concurrent repository queries.

Summary

Instagit’s MCP progress notification system enables real-time streaming updates through the following mechanisms:

• Unique progress tokens generated in src/index.ts to track individual tool invocations
• Standardized MCP notifications using the notifications/progress method with structured payloads
• 250-millisecond heartbeat intervals in src/api.ts ensuring continuous client feedback during streaming
• ProgressTracker and formatMessage utilities in src/kitt.ts for state management and human-readable status formatting

This architecture allows MCP-compatible clients to monitor AI analysis progress, display token usage statistics, and provide responsive user interfaces during long-running repository queries.

Frequently Asked Questions

What is the MCP progress notification system in Instagit?

The MCP progress notification system is a real-time communication protocol implemented in Instagit that streams status updates to clients during AI-powered repository analysis. It uses the Model-Context-Protocol standard to send periodic notifications containing token counts, elapsed time, and processing status while the ask_repo tool generates responses.

How often does Instagit send progress updates during streaming?

Instagit transmits progress updates every 250 milliseconds through a heartbeat mechanism defined in src/api.ts. This interval balances real-time feedback with network efficiency, ensuring clients receive frequent status updates without overwhelming the MCP communication channel during long-running AI analysis operations.

What information is included in an Instagit progress notification?

Each progress notification contains three key fields: the progressToken (unique request identifier), progress (current output token count from the ProgressTracker), and message (human-readable status string formatted by formatMessage in src/kitt.ts). This payload allows clients to display visual progress bars, token usage statistics, and status messages simultaneously.

Can Instagit’s progress notifications work with any MCP client?

Instagit’s progress notifications follow the standard MCP protocol using the notifications/progress method, making them compatible with any MCP-compliant client. However, the system gracefully handles unsupported clients by catching transmission errors in src/index.ts and continuing operation without progress feedback, ensuring robust interoperability across different MCP implementations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}