Documentation

1. Quickstart

mcp-injector is a local background daemon that reads your codebase, strips out unnecessary syntax, and feeds highly-compressed architectural maps directly to your AI. It saves massive amounts of tokens and prevents the AI from getting confused.

Step 1: Install the Daemon

Open your terminal, navigate to the root directory of your project, and run this command. It downloads the binary and will automatically attempt to configure your active IDEs (Cursor, Claude Desktop, VS Code, Devin, Antigravity) to use your current directory as the workspace.

curl -fsSL https://foldwork.dev/install | sh

Step 2: Restart Your IDE

The MCP server runs entirely locally and starts automatically when your IDE launches. There is no separate daemon process you need to manage. Simply quit and restart your IDE for the new configuration to take effect.

Step 3: Verify the Connection

Open your AI chat and prompt it with the following to verify the integration is working:

Use get_project_map to show me the structure of this project.

The AI will call the mcp-injector tool and return a compressed map of your entire codebase. If you see module names and dependency information, you are fully set up!

Manual Installation

If you prefer not to pipe to shell, or if you're offline:

1. Download the binary from the latest GitHub release.
2. Make it executable: chmod +x mcp-injector-*
3. Move it to your path: mv mcp-injector-* /usr/local/bin/mcp-injector
4. Proceed to Section 2 to manually configure your IDE.

2. Hook Up My Editor

Your AI editor needs to know that mcp-injector exists. The setup is slightly different for each editor, but they all require the absolute path to your codebase via the MCP_WORKSPACE environment variable.

Cursor

Open ~/.cursor/mcp.json (or go to Cursor Settings > Features > MCP) and add this:

{
  "mcpServers": {
    "mcp-injector": {
      "command": "/usr/local/bin/mcp-injector",
      "env": {
        "MCP_WORKSPACE": "/absolute/path/to/your/project"
      }
    }
  }
}

Claude Desktop

Open your config file (Mac: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json).

Add the exact same JSON snippet shown in the Cursor section above, save the file, and restart Claude completely.

Devin Desktop

Open ~/.codeium/windsurf/mcp_config.json and paste the exact same snippet shown in the Cursor section above.

Antigravity

Open ~/.gemini/antigravity/mcp_config.json. Note that Antigravity requires an explicit HOME environment variable:

{
  "mcpServers": {
    "mcp-injector": {
      "command": "/usr/local/bin/mcp-injector",
      "env": {
        "MCP_WORKSPACE": "/absolute/path/to/your/project",
        "HOME": "/home/your-username"
      }
    }
  }
}

VS Code (Cline / RooCode)

Create a .vscode/mcp.json file inside your workspace directory with the standard snippet. VS Code MCP extensions read this file dynamically.

Working on multiple projects?

Whenever you switch to a different project folder, just re-run curl -fsSL https://foldwork.dev/install | sh inside the new folder. The script updates your global configs automatically. Alternatively, run separate daemon instances pointing to different MCP_WORKSPACE paths.

3. Exposed MCP Tools API & Magic Prompts

You don't have to know how these tools work—the AI will call them automatically. However, you can explicitly prompt the AI to use these tools for precise control over your workflow.

get_project_map

Returns a compressed overview of the architecture. It automatically detects framework boundaries and groups files semantically.

Magic Prompt:

Use get_project_map to analyze my codebase and tell me how the main components fit together.

Advanced Parameters:

• tier (int): Compression level. Tier 3 (default) strips bodies. Tier 2 keeps comments. Tier 1 disables compression.
• unfolded_files (array): Specific file paths to serve at full resolution uncompressed.
• path_prefixes (array): Paths to restrict the map to a specific microservice.

injector_search

Fast BM25 full-text search over indexed symbols. Supports FTS5 boolean logic.

Magic Prompt:

Use injector_search to find "user AND auth" inside the src/services directory.

Advanced Parameters:

• search_paths (array): Optional list of directories to restrict the search scope.
• limit (int): Maximum number of search results to return (default is usually 10).

injector_diagram

Generates a Mermaid sequence diagram for a symbol by traversing outbound dependencies.

Magic Prompt:

Use injector_diagram to draw a Mermaid sequence diagram for the ProcessPayment function.

Advanced Parameters:

• max_depth (int): The maximum depth to traverse outbound dependencies (default is 3).

injector_blast_radius

Analyzes the architectural impact of changing a symbol by traversing the dependency graph. Supports inbound and outbound directional traversal.

Magic Prompt:

Use injector_blast_radius to find all inbound dependencies that call the SaveUser function.

Advanced Parameters:

• direction (string): Can be "inbound" (what depends on this) or "outbound" (what this depends on).

injector_git_context

Integrates with local Git history to surface commit context, authorship, and code evolution directly into the LLM context.

Magic Prompt:

Use injector_git_context to summarize the recent changes in the last 5 commits.

Advanced Parameters:

• limit (int): The maximum number of commits to retrieve (default is 3).

injector_inspect_table

Enables direct database introspection capabilities. Currently supports PostgreSQL and MySQL.

Magic Prompt:

Use injector_inspect_table to show me the schema for the users table.

Advanced Parameters:

• table_name (string): The precise name of the table to introspect.

injector_retrieve

Fetches the uncompressed source of a file from the local cache.

Magic Prompt:

Use injector_retrieve to show me the full implementation of UserService.java.

Advanced Parameters:

• start_line & end_line (int): Restrict retrieval to a specific line range snippet.
• expand_graph (bool): If true, resolves and appends 1st-degree dependencies automatically.

injector_regex_search

Bypasses FTS5 tokenization for exact punctuation or extended regex matching.

Magic Prompt:

Use injector_regex_search to find exact matches for "SELECT * FROM".

Advanced Parameters:

• is_regex (bool): Treat the search query as an extended POSIX regex pattern.

injector_write_file

Safe AI-assisted editing with fold-marker collision prevention.

Magic Prompt:

Use injector_write_file to save the updated handler logic to src/api/handler.go.

Advanced Parameters:

• None. Automatically handles overwrite safety and triggers re-indexing.

injector_stats

Shows daemon status, indexed files, compression ratios, and cache hit rates.

Magic Prompt:

Call injector_stats and tell me my current token savings.

Advanced Parameters:

• None.

injector_clear_cache

Wipes the SQLite index cache and triggers a clean cold-start full re-index.

Magic Prompt:

Use injector_clear_cache to completely wipe the local index.

Advanced Parameters:

• None.

4. Additional Features

Persistent AI Memory (Hidden Feature)

If you create a file at .foldwork/decisions.md in your project root, mcp-injector will silently inject the first 4KB of it directly into the AI's context on every single request. Use this to enforce architectural rules, styling guidelines, or team conventions globally.

Security First: Zero-Leak Guarantee

Enterprise security teams often block AI coding tools because developers accidentally leak sensitive credentials in their context window.

mcp-injector solves this locally. The daemon includes a built-in Shannon entropy filter that analyzes all AST strings and comments in real-time. If it detects high-entropy strings (like AWS Access Keys, SSH private keys, or database passwords), it dynamically redacts them as [REDACTED: high entropy] before they ever leave your machine. Your API credentials are never sent to the LLM.

Canonical Output Determinism

Anthropic's Context Caching (KV cache) relies on strict byte-for-byte matching of prompts. Foldwork guarantees byte-identical outputs across runs by applying deterministic sorting to all AST nodes. This ensures that unchanged files always hit the prompt cache, driving your API costs down by up to 90%.

Exclude Files (.mcp-ignore)

The daemon automatically respects your .gitignore rules. If you want to exclude additional files from AI indexing without ignoring them in Git, create a .mcp-ignore file in your workspace root.

# .mcp-ignore
# Exclude generated protobuf files
*.pb.go

# Exclude massive data fixtures
testdata/
fixtures/

Changes to .gitignore or .mcp-ignore are detected dynamically. Ignored files are purged from the cache instantly without a restart.

Git Branch Switching

mcp-injector automatically installs a post-checkout Git hook in your repository on startup. When you switch branches (e.g., git checkout feature-branch), the hook signals the background daemon to re-index the changed files.

This prevents the AI from reading stale codebase state.

If branch switching stops working, verify the hook is executable:

chmod +x .git/hooks/post-checkout

Smart File Watchers

mcp-injector hooks into your operating system's native file watching APIs (inotify on Linux, FSEvents on macOS). When you modify a file in your editor, the daemon detects the change and incrementally re-indexes the AST in the background within milliseconds, ensuring the AI always has the freshest context without manually triggering updates.

Interactive OS Limit Scaling

When indexing massive 100,000+ file monorepos, hitting Linux inotify file-watcher limits (ENOSPC) is common. Instead of crashing, Foldwork safely pauses operations, opens a direct /dev/tty interactive bridge to prompt the developer to scale their OS limits, and dynamically resumes indexing without requiring a restart.

Polyglot AST Parsing

The daemon provides Tier 1 full syntax tree compression (function folding, body stripping, deterministic sorting) for Go, Python, Java, TypeScript, JavaScript, C++, C, C#, and Rust. For any other language, it safely degrades to standard plaintext indexing, ensuring 100% repository coverage.

5. Bonus CLI Tools

These powerful commands can be run directly from your terminal, no AI required.

Check Token ROI (status)

See exactly how many tokens the daemon is saving you right now.

mcp-injector status

Find Bad Architecture (audit)

Instantly scans your entire codebase graph to identify structural weaknesses.

mcp-injector audit

This outputs lists of God Objects (high outbound coupling), Architectural Bottlenecks (high inbound coupling), and Circular Dependencies.

See What The AI Sees (inspect)

Simulates an LLM context retrieval. Shows the confidence score, the retrieved files, and traces the dependency graph based on your query.

mcp-injector inspect "payment processing"

Export The Graph (export)

Dumps the entire parsed repository graph (nodes and edges) to JSON for custom visualization scripts.

mcp-injector export > graph.json

6. Troubleshooting

A comprehensive guide to resolving issues at every phase of the mcp-injector lifecycle, from installation to production usage.

Phase 1: Setup & Installation

Phase 2: Editor Connection & Config

Phase 3: Indexing & Performance

Phase 4: Tool & AI Interaction

Phase 5: Licensing & Upgrades

Phase 6: OS-Specific Quirks

7. Under The Hood & Limitations

Automatic Git Context Awareness

You don't need to explain what you're working on to the AI. Every time the AI requests the project map, mcp-injector silently runs git diff and git status in the background. The AI automatically knows what branch you are on, what files you have modified (but not committed), and your last 5 commit messages. You can simply say: "Review my uncommitted changes."

Language Support

• Tier 1 (Full AST Compression): Go, Python, Java, TypeScript, JavaScript, C++, C, C#, and Rust. These languages get full function folding, body stripping, and deterministic sorting.
• Fallback: Any other language is safely indexed as standard plaintext.
• Polyglot: Files with mixed content (.vue, .svelte) only compress the <script> tags. Templates are preserved.

Hard Limits

• Massive Files: Any single file over 5MB is completely ignored.
• Minified Code: We skip heavily minified files (files with under 10 lines but over 50KB of text).
• Network Drives: We can't automatically detect file changes on NFS/network drives. The index will build on startup but won't update incrementally.

Uninstall

Run these two commands to completely scrub it from your system.

1. Delete the app:

sudo rm /usr/local/bin/mcp-injector

2. Delete the cache:

rm -rf ~/.mcp-injector/

Finally, open your IDE's MCP config file and delete the mcp-injector block, and remove .git/hooks/post-checkout if you don't want the git hook anymore.