How the Local HTTP Backend in GitNexus Powers AI Chat for the Web UI

The local HTTP backend in GitNexus is an Express-based server that exposes MCP over HTTP and REST API endpoints, enabling the browser-based web UI to stream AI chat responses while executing graph queries and hybrid searches against a local KuzuDB instance.

GitNexus implements a local HTTP backend that serves as the critical bridge between the browser-based web UI and the heavy-weight graph indexing engine running on the developer's machine. This architecture allows the web UI to remain lightweight while providing full access to AI-driven chat capabilities powered by local repository data. The backend combines two distinct communication layers: a stateful MCP over HTTP transport for streaming tool calls and a REST API for stateless data operations.

Architecture of the Local HTTP Backend

The GitNexus HTTP backend is built on Express and organizes functionality into two complementary layers that share a single LocalBackend instance containing the KuzuDB graph database.

MCP over HTTP Layer

The Model-Control-Protocol (MCP) over HTTP layer handles stateful streaming sessions between the Large Language Model (LLM) and the server. Mounted at /api/mcp in gitnexus/src/server/mcp-http.ts, this layer creates a StreamableHTTPServerTransport for each client session.

Key implementation details include:

• Session Management: Each client receives a unique session ID, with idle sessions automatically evicted after 30 minutes
• Shared State: The LocalBackend instance maintains the KuzuDB graph connection shared across all sessions
• Streaming Transport: The StreamableHTTPServerTransport enables real-time tool call streaming from the LLM back to the server

REST API Layer

The REST API provides stateless endpoints for graph queries, hybrid search, and file operations. Defined in gitnexus/src/server/api.ts, these endpoints use the same LocalBackend to answer tool calls without maintaining session state.

Available endpoints include:

• POST /api/query: Executes Cypher queries against the KuzuDB graph
• POST /api/search: Performs BM25 + semantic hybrid search across indexed repositories
• GET /api/file: Retrieves file contents for citation and context extraction

How the Web UI Connects to the Local HTTP Backend

The GitNexus web UI runs entirely in the browser using a WebWorker architecture (gitnexus-web/src/workers/ingestion.worker.ts) to offload AI processing from the main thread.

Initializing the Backend Agent

When a user opens the chat panel, the UI invokes initializeBackendAgent (lines 637-673 in the worker) to establish the connection to the local HTTP backend:

1. Configuration: Receives the HTTP base URL (backendUrl) and repository name
2. Wrapper Construction: Creates thin HTTP wrappers around the REST API:
   • createHttpExecuteQuery → POST /api/query (lines 75-88)
   • createHttpHybridSearch → POST /api/search (lines 97-119)
3. Agent Creation: Builds a CodebaseContext via Cypher queries and instantiates a GraphRAGAgent with the HTTP wrappers as tool callbacks

Streaming Chat Messages

Once initialized, chat messages flow through workerApi.chatStream (lines 716-744):

1. The worker forwards the message history to the currentAgent
2. The agent's tool callbacks invoke the HTTP wrappers, contacting the Express server to execute graph queries or hybrid searches
3. Results stream back through streamAgentResponse and render in the Right-Panel chat UI (gitnexus-web/src/components/RightPanel.tsx)

Code Implementation Examples

The following patterns demonstrate how the web UI integrates with the local HTTP backend:

// Create HTTP-backed tool wrappers (worker side)
const executeQuery = createHttpExecuteQuery(backendUrl, repoName);
const hybridSearch = createHttpHybridSearch(backendUrl, repoName);

// Initialize the backend-mode GraphRAG agent
await workerApi.initializeBackendAgent(
  providerConfig,          // e.g. { provider: 'openai', model: 'gpt-5.2-chat', apiKey: '…' }
  backendUrl,              // e.g. 'http://127.0.0.1:3000'
  repoName,                // repository identifier
  Array.from(fileContents.entries()), // file map needed for citations
  'my-project'             // optional display name
);

// Send a chat message from the UI
await workerApi.chatStream(messages, chunk => {
  // `chunk` is streamed back from the LLM; render it in the UI
  addChatChunk(chunk);
});

Summary

• The local HTTP backend in GitNexus combines an Express server with MCP over HTTP and REST API layers to bridge the browser UI with local graph infrastructure.
• MCP over HTTP (/api/mcp) manages stateful streaming sessions with 30-minute eviction, while the REST API (/api/query, /api/search) handles stateless data operations against KuzuDB.
• The WebWorker architecture keeps the UI responsive by offloading LLM agent initialization and chat streaming to a background worker that communicates via HTTP wrappers.
• All LLM-generated tool calls route through these HTTP endpoints, enabling the web UI to remain lightweight while accessing full repository intelligence.

Frequently Asked Questions

What is the purpose of the MCP over HTTP layer in GitNexus?

The MCP over HTTP layer provides a stateful transport mechanism for streaming tool calls between the LLM and the local backend. Mounted at /api/mcp in gitnexus/src/server/mcp-http.ts, it uses StreamableHTTPServerTransport to maintain persistent sessions with unique IDs, allowing real-time bidirectional communication while the REST API handles simple request-response operations.

How does GitNexus handle session management for AI chat?

GitNexus implements automatic session eviction where idle MCP sessions are terminated after 30 minutes of inactivity. Each client connection receives a unique session ID upon establishing the MCP over HTTP transport, and the LocalBackend instance maintains shared graph state (KuzuDB) across all active sessions while the transport layer manages per-session streaming contexts.

What endpoints does the REST API expose for the web UI?

The REST API in gitnexus/src/server/api.ts exposes several critical endpoints including POST /api/query for Cypher graph queries, POST /api/search for BM25 plus semantic hybrid search, and GET /api/file for retrieving file contents. These stateless endpoints use the same LocalBackend instance as the MCP layer to execute tool calls without maintaining session state between requests.

How does the WebWorker architecture benefit the GitNexus web UI?

The WebWorker architecture isolates CPU-intensive LLM processing and HTTP communication from the main browser thread, preventing UI freezing during chat operations. Implemented in gitnexus-web/src/workers/ingestion.worker.ts, the worker handles agent initialization, streams chat responses via workerApi.chatStream, and manages HTTP wrappers that communicate with the local backend, allowing the main thread to focus on rendering the chat interface in RightPanel.tsx.

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