Developer Context Agent

npm version license: MIT

Token-efficient codebase context for AI assistants.
Indexes your repo locally, ranks relevant files with hybrid retrieval, and returns token-budgeted context packs via MCP — no LLM required in this package.

Works with Cursor, Claude Desktop, Windsurf, and any Model Context Protocol client.

The host LLM (Cursor, Claude, etc.) does the reasoning.
This agent finds, ranks, and compresses codebase context.

Install

npm install -g developer-context-agent

Or use without installing:

npx developer-context-agent --help

Requirements: Node.js 20+

Quick start

cd your-project
context-agent index
context-agent pack --task "how does auth work"

Use with Cursor

Add .cursor/mcp.json in your project:

{
  "mcpServers": {
    "context-agent": {
      "command": "npx",
      "args": ["-y", "developer-context-agent", "mcp"],
      "env": {
        "REPO_PATH": "${workspaceFolder}"
      }
    }
  }
}

Restart Cursor, enable the MCP server in Settings → MCP, then chat as usual. The model can call get_context_pack before reading files.

Recommended Cursor rule (.cursor/rules/context-agent.mdc):

Before reading large files or searching the codebase manually, use context-agent MCP tools:
1. get_context_pack for the user's question
2. find_files / search_symbols only if more detail is needed

Use with Claude Desktop / other MCP clients

{
  "mcpServers": {
    "context-agent": {
      "command": "npx",
      "args": ["-y", "developer-context-agent", "mcp"],
      "env": {
        "REPO_PATH": "/absolute/path/to/your/repo"
      }
    }
  }
}

How it works

You ask in Cursor chat
       ↓
Host LLM calls get_context_pack("auth middleware")
       ↓
Agent: grep + symbols + import graph (+ optional vectors)
       ↓
Returns small markdown context pack (token-budgeted)
       ↓
Host LLM answers using that context

Local index is stored in .context-agent/ inside your project (SQLite). Nothing is sent to a cloud service by this package.

CLI

Command	Description
context-agent mcp	Start MCP server (stdio)
context-agent index [--repo path]	Build or refresh local index
context-agent status [--repo path]	Show index metadata
context-agent pack --task "…" [--repo path]	Print context pack to stdout

Examples:

context-agent index --repo .
context-agent status --repo .
context-agent pack --task "explain hybrid retrieval" --max-tokens 6000

MCP tools

Tool	Description
get_context_pack	Primary tool — token-budgeted context for a task
find_files	Rank files by relevance (grep + symbols + vectors)
search_symbols	TypeScript/JavaScript symbol search
grep	Sandboxed ripgrep
read_file	Sandboxed file read (optional line range)
index_repo	Build or refresh local index
index_status	Index health and chunk count

Configuration

Environment variables (optional):

Variable	Default	Description
REPO_PATH	cwd	Default repository path
TOKEN_BUDGET_DEFAULT	8000	Default context pack token budget
OLLAMA_BASE_URL	http://localhost:11434	Ollama API for embeddings
OLLAMA_EMBED_MODEL	nomic-embed-text	Embedding model
ALLOWED_REPO_ROOTS	—	Comma-separated repo path allowlist

Optional: semantic search with Ollama

Hybrid retrieval works without Ollama (grep + symbols + import graph).
For vector similarity search:

ollama pull nomic-embed-text
context-agent index

Development

Clone and work on the source repo:

git clone https://github.com/SinuxDev/developer-context-agent.git
cd developer-context-agent
npm install
npm test
npm run context-agent -- index --repo .
npm run mcp

Legacy HTTP server

An optional Fastify API (POST /chat, POST /runs) with Postgres/Redis is still in the codebase for supervised runs. It is not required for the MCP agent.

npm run docker:up
npm run db:migrate
npm run dev

See docs/IDE_BRIDGE.md for HTTP API details.

Links

• npm: https://www.npmjs.com/package/developer-context-agent
• Repository: https://github.com/SinuxDev/developer-context-agent
• Issues: https://github.com/SinuxDev/developer-context-agent/issues

License

MIT