instagit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Instalabs, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# instagit
+
+**Let Your Agent Instantly Understand the World's Code**
+
+An MCP server that gives coding agents instant insight into any Git repository — no guessing, no hallucination.
+
+## Quick Start
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "instagit": {
+      "command": "npx",
+      "args": ["-y", "instagit@latest"]
+    }
+  }
+}
+```
+
+Works with **Claude Code**, **Claude Desktop**, **Cursor**, and any MCP-compatible client. The `@latest` tag ensures you always get the most recent version.
+
+## Why
+
+Agents that integrate with external libraries are flying blind. They read docs (if they exist), guess at APIs, and hallucinate patterns that don't match the actual code. The result: broken integrations, wrong function signatures, outdated usage patterns, hours of debugging.
+
+When an agent can actually analyze the source code of a library or service it's integrating with, everything changes. It sees the real function signatures, the actual data flow, the patterns the maintainers intended. Integration becomes dramatically easier and less error-prone because the agent is working from ground truth, not guesses.
+
+## What Agents Can Do With This
+
+- **Integrate with any library correctly the first time** — "How do I set up authentication with this SDK?" gets answered from the actual code, not outdated docs or training data. Your agent sees the real constructors, the real config options, the real error types.
+- **Migrate between versions without the guesswork** — Point your agent at both the old and new version of a library. It can diff the actual implementations and generate a migration plan that accounts for every breaking change.
+- **Debug issues across repository boundaries** — When a bug spans your code and a dependency, your agent can read both codebases and trace the issue to its root cause — even into libraries you've never opened.
+- **Generate integration code that actually works** — Instead of producing plausible-looking code that fails at runtime, your agent writes integration code based on the real API surface: actual method names, actual parameter types, actual return values.
+- **Evaluate libraries before committing** — "Should we use library A or B?" Your agent can analyze both implementations, compare their approaches to error handling, test coverage, and architectural quality, and give you a grounded recommendation.
+- **Onboard to unfamiliar codebases in minutes** — Point your agent at any repo and ask how things work. It answers from the code itself, with file paths and line numbers, not from memory that may be months out of date.
+
+## Features
+
+- **Agent-native context** — Purpose-built for coding agents. Returns the exact context an AI needs to understand, modify, and reason about code.
+- **Architectural truth** — Goes beyond keyword search. Understands how components connect, why decisions were made, and where the real complexity lives.
+- **Any repo, any scale** — From weekend projects to massive monorepos. Public and private repositories, any Git host.
+- **Exact source citations** — Every claim traced back to specific files and line numbers. No hallucination, no hand-waving.
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `INSTAGIT_API_KEY` | API key from [instagit.com](https://instagit.com) | Auto-registers anonymous token |
+| `INSTAGIT_API_URL` | Custom API endpoint | Production API |
+
+### Authenticated Usage
+
+Sign up at [instagit.com](https://instagit.com) for higher rate limits and faster analysis:
+
+```json
+{
+  "mcpServers": {
+    "instagit": {
+      "command": "npx",
+      "args": ["-y", "instagit@latest"],
+      "env": {
+        "INSTAGIT_API_KEY": "ig_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Anonymous Usage
+
+No API key required — the server automatically registers an anonymous token on first use. Anonymous tokens are stored in `~/.instagit/token.json` and shared with the Python MCP server.
+
+## Tool: `ask_repo`
+
+Analyze any Git repository with AI.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `repo` | string | yes | Repository URL, shorthand (`owner/repo`), or any public Git URL |
+| `prompt` | string | yes | What to analyze or ask about the codebase |
+| `ref` | string | no | Branch, commit SHA, or tag (default: repository's default branch) |
+| `fast` | boolean | no | Use fast mode for quicker responses (default: true) |
+
+**Example prompts:**
+- "Explain the architecture and main components"
+- "Review the authentication implementation for security issues"
+- "How would I add a new API endpoint following existing patterns?"
+- "What would it take to upgrade from React 17 to 18?"
+
+## Requirements
+
+- Node.js 18+
+
+## License
+
+MIT — Copyright (c) 2026 Instalabs, LLC
+
+---
+
+Learn more at [instagit.com](https://instagit.com)

package/bin/instagit.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/index.js');

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,496 @@
+"use strict";
+
+// src/index.ts
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_zod = require("zod");
+
+// src/api.ts
+var import_eventsource_parser = require("eventsource-parser");
+
+// src/kitt.ts
+var WIDTH = 16;
+var SHADES = ["\u2588", "\u2593", "\u2592"];
+var BG = "\u2591";
+function makeKittFrame(pos, direction) {
+  const chars = Array(WIDTH).fill(BG);
+  for (let offset = 0; offset < SHADES.length; offset++) {
+    if (offset === 0) {
+      chars[pos] = SHADES[offset];
+    } else {
+      const trailPos = pos - offset * direction;
+      if (trailPos >= 0 && trailPos < WIDTH) {
+        chars[trailPos] = SHADES[offset];
+      }
+    }
+  }
+  return chars.join("");
+}
+var forward = [0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 15];
+var backward = [15, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0, 0];
+var LOGO_FRAMES = [];
+for (const i of forward) {
+  LOGO_FRAMES.push(makeKittFrame(i, 1));
+}
+for (const i of backward.slice(1)) {
+  LOGO_FRAMES.push(makeKittFrame(i, -1));
+}
+function formatDuration(seconds) {
+  if (seconds < 60) {
+    return `${Math.floor(seconds)}s`;
+  }
+  const minutes = Math.floor(seconds / 60);
+  const secs = Math.floor(seconds % 60);
+  return `${minutes}m ${secs}s`;
+}
+function formatTokens(count) {
+  if (count >= 1e3) {
+    return `${(count / 1e3).toFixed(1)}k`;
+  }
+  return String(count);
+}
+function createProgressTracker() {
+  return {
+    startTime: Date.now() / 1e3,
+    frameIndex: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    displayedTokens: 0,
+    lastStatus: "Connecting...",
+    done: false
+  };
+}
+function nextFrame(tracker) {
+  const frame = LOGO_FRAMES[tracker.frameIndex % LOGO_FRAMES.length];
+  tracker.frameIndex++;
+  return frame;
+}
+function elapsed(tracker) {
+  return formatDuration(Date.now() / 1e3 - tracker.startTime);
+}
+function animateTokens(tracker) {
+  const actual = tracker.inputTokens + tracker.outputTokens;
+  if (tracker.displayedTokens < actual) {
+    const step = Math.max(50, Math.floor((actual - tracker.displayedTokens) / 20));
+    tracker.displayedTokens = Math.min(tracker.displayedTokens + step, actual);
+  }
+  return tracker.displayedTokens;
+}
+function formatMessage(tracker, status, tokens) {
+  if (status) {
+    tracker.lastStatus = status;
+  }
+  if (tokens) {
+    if (tokens.input !== void 0) tracker.inputTokens = tokens.input;
+    if (tokens.output !== void 0) tracker.outputTokens = tokens.output;
+  }
+  const parts = [nextFrame(tracker), elapsed(tracker)];
+  const displayed = animateTokens(tracker);
+  if (displayed > 0) {
+    parts.push(`${formatTokens(displayed)} tokens`);
+  }
+  if (tracker.lastStatus) {
+    parts.push(tracker.lastStatus);
+  }
+  return parts.join(" \xB7 ");
+}
+
+// src/api.ts
+var DEFAULT_API_URL = "https://instagit--instagit-api-api.modal.run";
+function getApiUrl() {
+  return process.env.INSTAGIT_API_URL || DEFAULT_API_URL;
+}
+function buildModelString(repo, ref, fast) {
+  let model = repo;
+  if (fast) model += ":fast";
+  if (ref) model += `@${ref}`;
+  return model;
+}
+async function analyzeRepoStreaming(opts) {
+  const {
+    repo,
+    prompt,
+    ref = null,
+    fast = true,
+    token = null,
+    progressCallback
+  } = opts;
+  const tracker = opts.tracker ?? createProgressTracker();
+  const apiUrl = getApiUrl();
+  const model = buildModelString(repo, ref, fast);
+  const headers = { "Content-Type": "application/json" };
+  if (token) {
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+  const payload = {
+    model,
+    input: prompt,
+    stream: true
+  };
+  let collectedText = "";
+  let usage = {};
+  let heartbeatInterval = null;
+  if (progressCallback) {
+    heartbeatInterval = setInterval(async () => {
+      if (!tracker.done) {
+        try {
+          await progressCallback(formatMessage(tracker));
+        } catch {
+        }
+      }
+    }, 250);
+  }
+  try {
+    const response = await fetch(`${apiUrl}/v1/responses`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload)
+    });
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => "");
+      const error = new Error(`API error: ${response.status}`);
+      error.status = response.status;
+      error.body = errorBody;
+      throw error;
+    }
+    if (!response.body) {
+      throw new Error("No response body");
+    }
+    await new Promise((resolve, reject) => {
+      const parser = (0, import_eventsource_parser.createParser)({
+        onEvent(event) {
+          if (event.data === "[DONE]") {
+            resolve();
+            return;
+          }
+          let data;
+          try {
+            data = JSON.parse(event.data);
+          } catch {
+            return;
+          }
+          const eventType = data.type ?? "";
+          if (eventType === "response.reasoning.delta") {
+            const status = data.delta ?? "";
+            if (status) tracker.lastStatus = status;
+            if (data.tokens) {
+              if (data.tokens.input !== void 0) tracker.inputTokens = data.tokens.input;
+              if (data.tokens.output !== void 0) tracker.outputTokens = data.tokens.output;
+            }
+          } else if (eventType === "response.output_text.delta") {
+            const delta = data.delta ?? "";
+            collectedText += delta;
+            if (tracker.outputTokens === 0) {
+              tracker.outputTokens = Math.floor(collectedText.length / 4);
+            }
+            tracker.lastStatus = "Writing response...";
+          } else if (eventType === "response.completed") {
+            usage = data.response?.usage ?? {};
+          }
+        }
+      });
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      function read() {
+        reader.read().then(({ done, value }) => {
+          if (done) {
+            resolve();
+            return;
+          }
+          parser.feed(decoder.decode(value, { stream: true }));
+          read();
+        }).catch(reject);
+      }
+      read();
+    });
+  } finally {
+    tracker.done = true;
+    if (heartbeatInterval) {
+      clearInterval(heartbeatInterval);
+    }
+  }
+  return {
+    text: collectedText,
+    inputTokens: usage.input_tokens ?? 0,
+    outputTokens: usage.output_tokens ?? 0,
+    totalTokens: usage.total_tokens ?? 0,
+    tier: usage.tier ?? "free",
+    tokensRemaining: usage.tokens_remaining ?? 0,
+    upgradeHint: usage.upgrade_hint ?? null
+  };
+}
+
+// src/token.ts
+var import_fs = require("fs");
+var import_path = require("path");
+var import_os2 = require("os");
+
+// src/fingerprint.ts
+var import_crypto = require("crypto");
+var import_os = require("os");
+function getMacAddress() {
+  const nets = (0, import_os.networkInterfaces)();
+  for (const name of Object.keys(nets)) {
+    for (const iface of nets[name] ?? []) {
+      if (!iface.internal && iface.mac && iface.mac !== "00:00:00:00:00:00") {
+        return iface.mac;
+      }
+    }
+  }
+  return "00:00:00:00:00:00";
+}
+function macToInt(mac) {
+  return BigInt("0x" + mac.replace(/:/g, "")).toString();
+}
+function getMachineFingerprint() {
+  const parts = [
+    (0, import_os.hostname)(),
+    // platform.node()
+    (0, import_os.platform)(),
+    // platform.system() — "darwin", "linux", "win32"
+    (0, import_os.arch)(),
+    // platform.machine() — "x64", "arm64"
+    macToInt(getMacAddress())
+    // uuid.getnode() equivalent
+  ];
+  const platformMap = {
+    darwin: "Darwin",
+    linux: "Linux",
+    win32: "Windows"
+  };
+  parts[1] = platformMap[parts[1]] ?? parts[1];
+  const archMap = {
+    x64: "x86_64",
+    ia32: "i686"
+  };
+  parts[2] = archMap[parts[2]] ?? parts[2];
+  const raw = parts.join("|");
+  return (0, import_crypto.createHash)("sha256").update(raw).digest("hex").slice(0, 32);
+}
+
+// src/token.ts
+var CONFIG_DIR = (0, import_path.join)((0, import_os2.homedir)(), ".instagit");
+var TOKEN_FILE = (0, import_path.join)(CONFIG_DIR, "token.json");
+function getStoredToken() {
+  if (!(0, import_fs.existsSync)(TOKEN_FILE)) return null;
+  try {
+    const data = JSON.parse((0, import_fs.readFileSync)(TOKEN_FILE, "utf-8"));
+    return data.token ?? null;
+  } catch {
+    return null;
+  }
+}
+function storeToken(token) {
+  (0, import_fs.mkdirSync)(CONFIG_DIR, { recursive: true });
+  (0, import_fs.writeFileSync)(TOKEN_FILE, JSON.stringify({ token }));
+}
+function clearStoredToken() {
+  if ((0, import_fs.existsSync)(TOKEN_FILE)) {
+    (0, import_fs.unlinkSync)(TOKEN_FILE);
+  }
+}
+function getOrCreateToken() {
+  const apiKey = process.env.INSTAGIT_API_KEY;
+  if (apiKey) return apiKey;
+  return getStoredToken();
+}
+async function registerAnonymousToken(apiUrl) {
+  try {
+    const fingerprint = getMachineFingerprint();
+    const response = await fetch(`${apiUrl}/v1/auth/anonymous`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ fingerprint })
+    });
+    if (response.ok) {
+      const data = await response.json();
+      const token = data.token;
+      if (token) {
+        storeToken(token);
+        return token;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// src/index.ts
+var server = new import_mcp.McpServer({
+  name: "instagit",
+  version: "0.1.0"
+});
+var TOOL_DESCRIPTION = `Analyze any Git repository with AI. Point it at a repo and ask questions about the codebase. Use cases include:
+- Understanding unfamiliar codebases: 'Explain the architecture and main components'
+- Code review assistance: 'Review the authentication implementation for security issues'
+- Documentation generation: 'Document the public API of this library'
+- Dependency analysis: 'What external services does this app depend on?'
+- Onboarding help: 'How would I add a new API endpoint following existing patterns?'
+- Bug investigation: 'Where might null pointer exceptions occur in the data pipeline?'
+- Migration planning: 'What would it take to upgrade from React 17 to 18?'`;
+server.tool(
+  "ask_repo",
+  TOOL_DESCRIPTION,
+  {
+    repo: import_zod.z.string().describe(
+      "Repository to analyze. Accepts GitHub URLs (https://github.com/owner/repo), shorthand (owner/repo), GitLab/Bitbucket URLs, or any public Git URL"
+    ),
+    prompt: import_zod.z.string().describe("What to analyze or ask about the codebase"),
+    ref: import_zod.z.string().nullable().optional().default(null).describe("Branch, commit SHA, or tag to analyze (default: repository's default branch)"),
+    fast: import_zod.z.boolean().optional().default(true).describe("Use fast mode for quicker responses")
+  },
+  async ({ repo, prompt, ref, fast }, extra) => {
+    const apiUrl = getApiUrl();
+    const tracker = createProgressTracker();
+    const sendProgress = async (message) => {
+      try {
+        await extra.sendNotification({
+          method: "notifications/progress",
+          params: {
+            progressToken: `ask_repo_${Date.now()}`,
+            progress: tracker.outputTokens,
+            message
+          }
+        });
+      } catch {
+      }
+    };
+    let token = getOrCreateToken();
+    if (!token) {
+      await sendProgress(formatMessage(tracker, "Registering anonymous token..."));
+      token = await registerAnonymousToken(apiUrl);
+      if (!token) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Unable to register anonymous token. This may be because you've reached the limit of 3 tokens per IP address.\n\nTo continue using Instagit:\n1. Sign up for a free account at https://instagit.ai/signup\n2. Get an API key from your dashboard\n3. Set INSTAGIT_API_KEY in your MCP configuration"
+            }
+          ]
+        };
+      }
+    }
+    await sendProgress(formatMessage(tracker, "Connecting..."));
+    const callApi = async (authToken) => {
+      return analyzeRepoStreaming({
+        repo,
+        prompt,
+        ref,
+        fast,
+        token: authToken,
+        progressCallback: sendProgress,
+        tracker
+      });
+    };
+    let result;
+    try {
+      result = await callApi(token);
+    } catch (err) {
+      const error = err;
+      if (error.message?.includes("fetch failed") || error.message?.includes("ECONNREFUSED")) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Could not connect to Instagit API at ${apiUrl}. Make sure the API server is running.`
+            }
+          ]
+        };
+      }
+      if (error.status === 429) {
+        let rateLimitUntil;
+        try {
+          const errorData = JSON.parse(error.body ?? "{}");
+          rateLimitUntil = errorData.rate_limit_until;
+        } catch {
+        }
+        const resetInfo = rateLimitUntil ? `
+Credits will reset at: ${rateLimitUntil}
+` : "";
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Rate limit exceeded. Your free credits have been exhausted.
+${resetInfo}
+To continue using Instagit immediately:
+- Upgrade to Pro ($20/mo) for 10x more credits and faster analysis
+- Visit: https://instagit.ai/pricing`
+            }
+          ]
+        };
+      }
+      if (error.status === 401) {
+        clearStoredToken();
+        const newToken = await registerAnonymousToken(apiUrl);
+        if (newToken) {
+          try {
+            result = await callApi(newToken);
+          } catch (retryErr) {
+            const retryError = retryErr;
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `API error after re-auth: ${retryError.status ?? retryError.message}`
+                }
+              ]
+            };
+          }
+        } else {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Authentication failed. Unable to register a new token.\n\nPlease set INSTAGIT_API_KEY in your MCP configuration, or visit https://instagit.ai/signup to create an account."
+              }
+            ]
+          };
+        }
+      }
+      if (!result) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `API error: ${error.status ?? ""} ${error.message}`
+            }
+          ]
+        };
+      }
+    }
+    let responseText = result.text;
+    const footerParts = [];
+    if (result.totalTokens > 0) {
+      footerParts.push(
+        `Tokens: ${result.inputTokens.toLocaleString()} input, ${result.outputTokens.toLocaleString()} output, ${result.totalTokens.toLocaleString()} total`
+      );
+    }
+    if (result.tier) {
+      footerParts.push(`Tier: ${result.tier}`);
+    }
+    if (result.tokensRemaining > 0) {
+      footerParts.push(`Credits remaining: ${result.tokensRemaining.toLocaleString()}`);
+    }
+    if (footerParts.length > 0) {
+      responseText += "\n\n---\n" + footerParts.join(" | ");
+    }
+    if (result.upgradeHint) {
+      responseText += `
+
+${result.upgradeHint}`;
+    }
+    return {
+      content: [{ type: "text", text: responseText }]
+    };
+  }
+);
+async function main() {
+  const transport = new import_stdio.StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "instagit",
+  "version": "0.1.0",
+  "description": "MCP server for Instagit — AI-powered Git repository analysis for coding agents",
+  "author": "Instalabs, LLC",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "bin": {
+    "instagit": "./bin/instagit.js"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs --dts --clean",
+    "dev": "tsup src/index.ts --format cjs --watch",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "eventsource-parser": "^3.0.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "git",
+    "repository",
+    "analysis",
+    "ai",
+    "claude",
+    "coding-agent",
+    "model-context-protocol"
+  ],
+  "homepage": "https://instagit.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AugmentedMind/instagit-worker"
+  }
+}