Flashlight

MCP Server that uses DeepSeek's 1M context window for whole-codebase code search.

How it works

Flashlight loads your entire codebase into DeepSeek's context, then uses LLM understanding to find relevant code — no embeddings, no keyword matching, just brute-force full-context search.

It relies on DeepSeek's prefix caching for repeat queries: as long as the same prefix (system instructions + base code) is sent, tokens are served from cache (¥0.02/million tokens vs ¥1/million tokens for miss).

For large projects exceeding the 1M token limit, Flashlight automatically shards the codebase by directory, queries all shards in parallel, and merges results.

Setup

1. Install

npm install -g @1percentsync/flashlight

2. Get a DeepSeek API key

Get one at platform.deepseek.com.

3. Configure MCP

Add to your MCP client config:

Claude Code (~/.claude.json under mcpServers):

{
  "flashlight": {
    "command": "flashlight",
    "env": {
      "DEEPSEEK_API_KEY": "sk-..."
    }
  }
}

Flashlight detects the workspace from MCP roots when the client provides them. If roots are unavailable, it falls back to the server process working directory.

Usage

The server exposes a single tool search with parameters:

| Parameter | Required | Description | |-----------|----------|-------------| | query | Yes | Natural language description of the code to find | | scope | No | Optional workspace-relative directory prefix (e.g. app or framework/src). Omit to search the entire workspace. Do not pass ., ./, absolute paths, or paths outside the current workspace. | | file_types | No | File extensions to filter (e.g. [".ts", ".py"]) |

Output

Results are returned as code snippets — the matched line ranges with line numbers.

Configuration

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | DEEPSEEK_API_KEY | (required) | DeepSeek API key | | DEEPSEEK_BASE_URL | https://api.deepseek.com | DeepSeek API base URL | | FLASHLIGHT_MODEL | deepseek-v4-flash | Model (deepseek-v4-flash or deepseek-v4-pro) | | FLASHLIGHT_REASONING_EFFORT | max | Thinking effort (high or max) | | FLASHLIGHT_CHANGE_THRESHOLD | 0.1 | Ratio of changed tokens to trigger base rebuild | | FLASHLIGHT_MAX_CONTEXT_TOKENS | 900000 | Max tokens per shard (triggers auto-sharding when exceeded) |

Project-level config

Create .flashlight/config.json in the workspace root to customize file extensions per project:

{
  "ext_whitelist": [".mdx", ".astro"],
  "ext_whitelist_override": false
}

| Field | Default | Description | |-------|---------|-------------| | ext_whitelist | [] | File extensions to include | | ext_whitelist_override | false | true = only index listed extensions; false = merge with global defaults |

Priority: project config > FLASHLIGHT_EXT_WHITELIST env var > built-in defaults.

The config is read once at process start. Changes require restarting the agent environment.

How caching works

Flashlight relies on DeepSeek's prefix caching. On first query, it sends all code and saves a base snapshot. On subsequent queries:

1. Detect file changes against the saved base
2. If changed tokens exceed FLASHLIGHT_CHANGE_THRESHOLD (default 10%) — rebuild the base entirely
3. Otherwise — reuse the stored base text and append only changed files as incremental context

This ensures the prompt prefix stays stable across queries, maximizing cache hit rate.

Sharding (large projects)

When a project exceeds FLASHLIGHT_MAX_CONTEXT_TOKENS, Flashlight automatically:

1. Splits files by directory — tries the whole project first, then recursively splits by top-level directories until each group fits
2. Queries all shards in parallel
3. Merges and deduplicates results

Each shard maintains independent cache state. Shard boundaries only change when a shard overflows (split eagerly, merge lazily).

Logs

Logs are written to .flashlight/flashlight.log in the workspace root. Each query logs:

• Snapshot size and shard plan
• File change detection
• Per-shard query cache hit ratio
• Search results

Cost

With deepseek-v4-flash on a ~50K token codebase:

| Operation | Cost | |-----------|------| | First query (build cache) | ~¥0.05 | | Subsequent query (cache hit) | ~¥0.001 + output tokens |

License

ISC