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