A host-agnostic TypeScript code intelligence engine that indexes your codebase into searchable, symbol-centric records — exposable to any AI agent via MCP.
FreeContext parses TypeScript and JavaScript codebases using tree-sitter, extracts a structured symbol index (functions, classes, interfaces, imports, exports, and call sites), and makes that index queryable by name, file, or symbol kind in Phase 1.
The index is exposed as an MCP (Model Context Protocol) server over Streamable HTTP, giving AI agents like Claude Code and Codex structured, low-hallucination access to your codebase without raw file dumps.
# Install
npm install -g free-context
# or use npx: npx free-context <command>
# Index your project
free-context index ./my-project
# Search symbols
free-context search "AuthService"
# Search file paths
free-context search-paths auth
# List symbols in a file
free-context search --file src/auth/service.ts
# Find classes in a file
free-context search --file src/auth/service.ts --kind class
# Find callers for a symbol
free-context who-calls AuthService
# Start the MCP server
free-context serve ./my-project --port 3100
# Start with local embeddings via Ollama
free-context serve ./my-project --storage lancedb --embed
# Smoke-test the MCP endpoint with the SDK client
npm run mcp:smokeWhen --embed is enabled, FreeContext defaults to the local ollama backend with qwen3-embedding:0.6b.
# One-time model pull
ollama pull qwen3-embedding:0.6b
# Index with persistent storage and local embeddings
free-context index . --storage lancedb --embed
# Or start the MCP server with embeddings enabled
free-context serve . --storage lancedb --embedDefault behavior when --embed is set with no explicit embedder:
- embedder:
ollama - model:
qwen3-embedding:0.6b - host:
http://127.0.0.1:11434
free-context serve . \
--storage lancedb \
--embed \
--embedder ollama \
--embedding-base-url http://10.0.0.20:11434You can also set:
export OLLAMA_HOST=http://10.0.0.20:11434
export OLLAMA_EMBEDDING_MODEL=qwen3-embedding:0.6bfree-context index . \
--storage lancedb \
--embed \
--embedder ollama \
--embedding-model-id qwen3-embedding:8b \
--embedding-dimensions 4096If you switch models or dimensions, rebuild the index. FreeContext now fails fast instead of mixing incompatible vectors in one LanceDB index.
free-context serve . \
--storage lancedb \
--embed \
--embedder openai_compatible \
--embedding-base-url http://127.0.0.1:8080/v1 \
--embedding-model-id text-embedding-qwenOptional environment variables:
export OPENAI_COMPATIBLE_BASE_URL=http://127.0.0.1:8080/v1
export OPENAI_COMPATIBLE_MODEL=text-embedding-qwen
export OPENAI_COMPATIBLE_API_KEY=...Start FreeContext once for the repo you want to expose:
free-context serve . --storage lancedb --port 3100Then connect your coding agent to:
http://127.0.0.1:3100/mcp
Or generate the setup instructions for a specific client with one command:
free-context setup-agent claude-code
free-context setup-agent codex --scout-provider openrouterRecommended instruction snippet for any agent config or project rules file:
Use the free-context MCP server for symbol lookup, path search, call graph queries, and codebase summaries before falling back to raw file search.
claude mcp add --transport http --scope user free-context http://127.0.0.1:3100/mcpVerify inside Claude Code with /mcp.
Add this to ~/.cursor/mcp.json or .cursor/mcp.json in your project:
{
"mcpServers": {
"free-context": {
"url": "http://127.0.0.1:3100/mcp"
}
}
}codex mcp add free-context --url http://127.0.0.1:3100/mcp
codex mcp listOr add this to ~/.codex/config.toml:
[mcp_servers.free-context]
url = "http://127.0.0.1:3100/mcp"Add this to ~/.gemini/settings.json or .gemini/settings.json in your project:
{
"mcpServers": {
"free-context": {
"httpUrl": "http://127.0.0.1:3100/mcp"
}
}
}Add this to ~/.config/opencode/opencode.json or opencode.json in your project:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"free-context": {
"type": "remote",
"url": "http://127.0.0.1:3100/mcp",
"enabled": true
}
}
}Use free-context to find who calls dispatchPlugin.Use free-context search_paths to show everything under apps/gateway/src.Use free-context codebase_map and summarize the repo structure.Use free-context find_symbol for AuthService before editing anything.
Keep the stack small:
free-context: local symbol, path, graph, and codebase retrievalcontext7: current framework and library docsplaywright: browser automation and UI verificationgithub: optional for PRs, issues, and repo-hosting workflowweb-search: optional if your client does not already include a strong built-in web tool
Do not add a separate shell-execution MCP if your client already has native shell/file tools. Use the client’s built-in shell for tests, git, ripgrep, and edits.
Use a cheap scout model for:
- context packet assembly
- test-log triage
- broad repo scouting
- summarization over FreeContext tool results
free-context setup-agent <client> --scout-provider <provider> prints a simple env template for that provider.
git clone https://github.com/apethree/FreeContext.git
cd FreeContext
npm install
npm run buildAll Planned Phases Complete
The engine can parse TypeScript/JavaScript, persist symbols in memory or LanceDB, run full-text, semantic, hybrid, and path retrieval, build call/import/inheritance edges, skip unchanged files during re-index, and expose all of that through an MCP server at /mcp. See PROGRESS.md for the exact verification status.
Semantic indexing and search fail fast if the active embedding model or vector dimensions do not match the existing LanceDB index. Rebuild the index when you switch embedding models.
| Language | Extensions | Status |
|---|---|---|
| TypeScript | .ts |
✅ Phase 1 |
| TypeScript JSX | .tsx |
✅ Phase 1 |
| JavaScript | .js |
✅ Phase 1 |
| JavaScript JSX | .jsx |
✅ Phase 1 |
See docs/architecture/overview.md for the full system design.
FileProvider → Parser → Indexer → IndexStorage
↓
SearchService
↓
CodeIntelEngine (public façade)
↓
CLI / MCP Server
| Document | Purpose |
|---|---|
| docs/architecture/overview.md | System design and data flow |
| docs/architecture/data-model.md | CodeSymbolRow, EdgeRow schema |
| docs/adr/ | Architecture decision records |
| docs/how-to/index-a-project.md | Step-by-step indexing guide |
| docs/reference/cli.md | CLI reference |
| docs/reference/config.md | Config schema |
| docs/reference/mcp-config.md | MCP server and client config |
| docs/reference/mcp-config.md#client-setups | Copy-paste MCP setup for popular coding agents |
| docs/roadmap.md | Phase roadmap |
| PLAN.md | Detailed implementation plan |
| PROGRESS.md | Phase-by-phase progress tracker |
Read AGENTS.md for how to work with this repo using AI agents. Before opening a PR, run:
npm run typecheck
npm run test
npm run buildMIT