Free Context

FreeContext

一个与主机无关的TypeScript代码智能引擎，将您的代码库索引到可搜索的、以符号为中心的记录中——可通过MCP向任何AI代理公开。

______________________________________________________________________

它做什么

FreeContext使用树状图解析TypeScript和JavaScript代码库，提取结构化符号索引（函数、类、接口、导入、导出和调用站点），并在第一阶段按名称、文件或符号类型查询该索引。

该指数作为 MCP（模型上下文协议）服务器 通过流式HTTP，让Claude Code和Codex等人工智能代理能够以结构化、低幻觉的方式访问您的代码库，而无需原始文件转储。

______________________________________________________________________

快速入门

# Install
npm install -g free-context
# or use npx: npx free-context 

# 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:smoke

当 --embed 启用后，FreeContext默认为本地 ollama 后端与 qwen3-embedding:0.6b.

嵌入设置

默认本地Ollama流量

# 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 --embed

默认行为 --embed 设置时没有显式嵌入器：

• 嵌入者： ollama
• 型号： qwen3-embedding:0.6b
• 主机： http://127.0.0.1:11434

远程Ollama主机

free-context serve . \
  --storage lancedb \
  --embed \
  --embedder ollama \
  --embedding-base-url http://10.0.0.20:11434

您还可以设置：

export OLLAMA_HOST=http://10.0.0.20:11434
export OLLAMA_EMBEDDING_MODEL=qwen3-embedding:0.6b

更改嵌入模型

free-context index . \
  --storage lancedb \
  --embed \
  --embedder ollama \
  --embedding-model-id qwen3-embedding:8b \
  --embedding-dimensions 4096

如果切换模型或维度，请重建索引。FreeContext现在失败得很快，而不是在一个LanceDB索引中混合不兼容的向量。

OpenAI兼容的本地或远程服务器

free-context serve . \
  --storage lancedb \
  --embed \
  --embedder openai_compatible \
  --embedding-base-url http://127.0.0.1:8080/v1 \
  --embedding-model-id text-embedding-qwen

可选环境变量：

export OPENAI_COMPATIBLE_BASE_URL=http://127.0.0.1:8080/v1
export OPENAI_COMPATIBLE_MODEL=text-embedding-qwen
export OPENAI_COMPATIBLE_API_KEY=...

______________________________________________________________________

与编码代理一起使用

为要公开的仓库启动FreeContext一次：

free-context serve . --storage lancedb --port 3100

然后将您的编码代理连接到：

http://127.0.0.1:3100/mcp

或者使用一个命令为特定客户端生成设置说明：

free-context setup-agent claude-code
free-context setup-agent codex --scout-provider openrouter

任何代理配置或项目规则文件的推荐说明片段：

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/mcp

在Claude Code内部进行验证 /mcp.

光标

将此添加到 ~/.cursor/mcp.json 或 .cursor/mcp.json 在您的项目中：

{
  "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 list

或将此添加到 ~/.codex/config.toml:

[mcp_servers.free-context]
url = "http://127.0.0.1:3100/mcp"

双子星命令行工具

将此添加到 ~/.gemini/settings.json 或 .gemini/settings.json 在您的项目中：

{
  "mcpServers": {
    "free-context": {
      "httpUrl": "http://127.0.0.1:3100/mcp"
    }
  }
}

开源代码

将此添加到 ~/.config/opencode/opencode.json 或 opencode.json 在您的项目中：

{
  "$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.

推荐的MCP堆栈

保持堆栈较小：

• free-context：本地符号、路径、图形和代码库检索
• context7：当前框架和库文档
• playwright：浏览器自动化和UI验证
• github：PR、问题和回购托管工作流的可选项
• web-search：如果您的客户端尚未包含强大的内置web工具，则可选

如果您的客户端已经具有本机shell/文件工具，则不要添加单独的shell执行MCP。使用客户端的内置shell进行测试、git、ripgrep和编辑。

侦察员模型

使用廉价的侦察模型：

• 上下文数据包组装
• 测试日志分类
• 广泛回购侦察
• FreeContext工具结果总结

free-context setup-agent --scout-provider 为该提供者打印一个简单的env模板。

______________________________________________________________________

安装（来源）

git clone https://github.com/apethree/FreeContext.git
cd FreeContext
npm install
npm run build

______________________________________________________________________

电流相位

所有计划阶段均已完成

该引擎可以解析Types/JavaScript，将符号持久化在内存或LanceDB中，运行全文、语义、混合和路径检索，构建调用/导入/继承边，在重新索引期间跳过未更改的文件，并通过MCP服务器公开所有这些 /mcp。参见 PROGRESS.md 以获取确切的验证状态。

如果活动嵌入模型或向量维度与现有的LanceDB索引不匹配，语义索引和搜索会很快失败。切换嵌入模型时重建索引。

______________________________________________________________________

支持的语言

______________________________________________________________________

架构概述

看 docs/architecture/overview.md 对于整个系统的设计。

FileProvider → Parser → Indexer → IndexStorage
                                       ↓
                                  SearchService
                                       ↓
                           CodeIntelEngine (public façade)
                                       ↓
                              CLI   /   MCP Server

______________________________________________________________________

文档

______________________________________________________________________

贡献

阅读 代理商.md 了解如何使用AI代理使用此仓库。在打开PR之前，运行：

npm run typecheck
npm run test
npm run build

______________________________________________________________________

许可证

麻省理工学院