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 caches the codebase context on DeepSeek's side, so repeat queries are fast and cheap (cache hit price: ¥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-..."
    }
  }
}

Usage

The server exposes a single tool search with parameters:

Output Modes

Results are returned in one of three formats (tried in order):

1. Full files — all matched files with line numbers (if total ≤ 50K chars)
2. Snippets — only the matched line ranges (if total ≤ 50K chars)
3. Index — file paths and line ranges only (caller should use Read to view code)

Configuration

All via environment variables:

How caching works

On first query, Flashlight sends all code to DeepSeek and saves a base snapshot. On subsequent queries:

1. Probe — check if DeepSeek's cache is still alive
2. If alive — detect file changes, send only changed files + new query
3. If expired — rebuild the base

After each rebuild, activation requests establish cache for future probes and queries.

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).

Cache Keepalive (Docker)

For long-lived cache preservation, deploy the keeper service:

docker run -d -p 3100:3100 ghcr.io/1percentsync/flashlight-keeper

Or with docker compose (keeper/docker-compose.yml):

cd keeper && docker compose up -d

Then set FLASHLIGHT_KEEPER_URL=http://localhost:3100 in your MCP config.

How it works

The keeper learns the actual DeepSeek cache TTL through observation, then schedules activations just in time.

1. Sentinel: per model, creates a tiny throwaway cache, waits ~95% of estimated TTL, probes once. If alive → TTL estimate up. If dead → TTL estimate down. Cost: ~¥0.002/day.
2. Adaptive timing: 24 hourly buckets (UTC) per model, each with its own TTL estimate. Peak hours may have shorter TTL; off-peak may have longer. The keeper adapts automatically.
3. Task activation: when a task's time since last activation reaches estimated_TTL × 80%, keeper probes and re-activates it. If the cache is already dead (shouldn't happen if sentinel timing is correct), the task is removed.
4. TTL persistence: learned estimates are saved to disk (/app/data/ttl_estimate.json) and survive container restarts.

Keeper environment variables

Logs

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

• Snapshot size and shard plan
• Cache probe result (hit/miss)
• File change detection
• Per-shard query cache hit ratio
• Search results
• Activation status

Cost

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

License

ISC