内容
<p align="center">
<img src="public/infimium-logo.png" alt="Infimium" width="120" />
</p>
人工智能代理的私有搜索MCP。网页 · 代码 · 本地文档 · 依赖图 —— 一个端点，您的机器。
[](https://www.npmjs.com/package/infimium)
[](LICENSE)
[](https://github.com/infimium-ai/infimium-agent)
## 问题
代理需要精确的上下文，但大型仓库使得这一过程变得昂贵且快速。
关键词搜索很脆弱：它会错过意图、别名和实际重要的符号。
```
20 万行代码
代理读取所有内容 → 上下文丢失 + 高成本
grep "价格计算" → 忽略 calcPropertyValue()
```
## 使用 Infimium
Infimium 在本地索引您的文档、代码符号和依赖关系图。
代理询问聚焦的工具以获取正确的上下文，而不是读取整个项目。
```
工具：semantic_code_search
查询： "价格计算逻辑"
→ services/property/calc.ts:142 · calcPropertyValue()
→ 被以下文件导入： listing.ts, tax.ts, pdf-generator.ts, calc.test.ts
```
## 工具
`web_search` — Brave 网络搜索，带有重试和简洁的源代码片段。
`fetch_url` — 获取 HTML，去除噪音，返回 Markdown 或文本。
`query_local_docs` — 本地文档 RAG，支持 `.md`、`.txt`、`.html` 和 `.pdf`。
`semantic_code_search` — 区分器：tree-sitter 符号 + 本地嵌入，实现基于语义的代码搜索。
`dep_graph` — 区分器：SQLite 导入图，适用于“定义在哪里，谁导入它？”
`shell` — 允许列出的命令运行器，带有阻止模式、超时和输出限制。
`plan` — 区分器：检索语义代码上下文和依赖关系边，然后制定实施计划。
`status` — CLI 健康检查，适用于索引文档、代码符号、依赖关系图关系、监视项目、数据库大小和上次索引时间。
`doctor` — CLI 设置检查，适用于 Node/npm、Ollama、ChromaDB、`.env` 和索引准备情况。
## 为什么选择自托管
您的代码索引、嵌入和依赖关系图 —— 所有这些都在您的机器上。没有任何数据离开。
- 嵌入在本地运行，带有 Ollama。
- 无供应商锁定：MCP、SQLite、ChromaDB、TypeScript。
- 适用于隔离环境的 air-gapped 环境。
## 快速入门
```bash
git clone https://github.com/infimium/infimium && cd infimium
cp .env.example .env # 添加您的 SEARCH_API_KEY
./scripts/setup.sh
```
## 设置指南
### npm 包
需要 Node.js 22.5+。
安装：
```bash
npm i infimium
```
创建 `.env`：
```bash
cp .env.example .env
```
配置：
```bash
SEARCH_API_KEY=您的 brave_api_key
SEARCH_PROVIDER=brave
LOCAL_DOCS_PATH=/绝对路径/到/docs
CODEBASE_PATH=/绝对路径/到/code
OLLAMA_HOST=http://localhost:11434
CHROMADB_HOST=http://localhost:8000
SHELL_ALLOWLIST=ls,git,npm,npx
```
启动 Ollama：
```bash
ollama serve
ollama pull nomic-embed-text
```
在 `http://localhost:8000` 启动 ChromaDB：
```bash
chroma run --path ./chroma_db --host localhost --port 8000
```
或使用 Docker：
```bash
docker run -p 8000:8000 -v ./chroma_db:/chroma/chroma chromadb/chroma
```
索引文档和代码：
```bash
npx infimium index
```
检查状态：
```bash
npx infimium status
```
检查设置健康状况：
```bash
npx infimium doctor
```
生成一个有根据的实施计划：
```bash
npx infimium plan --dry-run "在身份验证端点添加速率限制"
npx infimium plan --write "在身份验证端点添加速率限制"
```
提供 MCP 服务：
```bash
npx infimium serve
```
`infimium status` 不是硬编码的。它读取本地 SQLite 元数据和 ChromaDB 计数。如果它显示“0 文件”，请在设置 `LOCAL_DOCS_PATH` 和 `CODEBASE_PATH` 后运行 `npx infimium index`。
### Docker
```bash
cp .env.example .env
```
设置：
```bash
SEARCH_API_KEY=...
LOCAL_DOCS_PATH=./docs
CODEBASE_PATH=./code
```
运行：
```bash
./scripts/setup.sh
```
设置脚本启动 ChromaDB，启动 Infimium，拉取 `nomic-embed-text`，运行索引，并打印 MCP 配置。
### 本地开发
安装依赖项：
```bash
npm install
```
需要 Node.js 22.5+。
启动 Ollama：
```bash
ollama serve
ollama pull nomic-embed-text
```
在 `http://localhost:8000` 启动 ChromaDB。
创建 `.env`：
```bash
cp .env.example .env
```
使用本地路径：
```bash
LOCAL_DOCS_PATH=/绝对路径/到/docs
CODEBASE_PATH=/绝对路径/到/code
OLLAMA_HOST=http://localhost:11434
CHROMADB_HOST=http://localhost:8000
```
索引：
```bash
npm run index
```
提供服务：
```bash
npm start -- serve
```
检查状态：
```bash
npm run status
```
检查设置：
```bash
npm run doctor
```
计划代码更改：
```bash
npm run plan -- --dry-run "在身份验证端点添加速率限制"
```
## 工具简介
| 工具 | 输入 | 要求 | 输出 |
| --- | --- | --- | --- |
| `web_search` | `query`, `max_results` | Brave API 密钥 | 排名的网络结果 |
| `fetch_url` | `url`, `extract` | 网络访问 | 清洁的 Markdown/文本 |
| `query_local_docs` | `query`, `top_k` | 索引文档，Ollama，ChromaDB | 匹配的文档块 |
| `semantic_code_search` | `query`, `language`, `top_k` | 索引代码，Ollama，ChromaDB | 匹配的符号，文件和行范围 |
| `dep_graph` | `symbol_name` | 索引代码图 | 定义文件，导入者，导入 |
| `shell` | `command`, `cwd`, `timeout` | 允许列出的命令 | stdout, stderr, exit code |
| `plan` | `task`, `dry_run`, `write_plan`, `output_path`, `top_k`, `language` | 索引代码，Ollama，ChromaDB | 实施计划或检索上下文 |
| `status` | 无 | 本地 SQLite/ChromaDB 状态 | 索引健康摘要 |
| `doctor` | 无 | 本地环境 | 设置通过/失败报告 |
## 使用工具
在将 Infimium 添加到 Claude Desktop、Cursor 或 Windsurf 后，请要求代理使用特定的 Infimium 工具名称。MCP 客户端将 JSON 输入发送到 Infimium；您不使用 HTTP 调用这些工具。
### `web_search`
用于当前网络结果。
提示：
```text
使用 Infimium web_search 查找最近的 MCP 服务器示例。
```
工具输入：
```json
{
"query": "最近的 MCP 服务器示例",
"max_results": 5
}
```
要求：
```bash
SEARCH_API_KEY=...
SEARCH_PROVIDER=brave
```
### `fetch_url`
用于获取页面并提取可读内容。
提示：
```text
使用 Infimium fetch_url 获取 https://modelcontextprotocol.io 并总结它。
```
工具输入：
```json
{
"url": "https://modelcontextprotocol.io",
"extract": "markdown"
}
```
`extract` 可以是 `markdown` 或 `text`。
### `query_local_docs`
在索引本地文档后使用。
提示：
```text
使用 Infimium query_local_docs 查找 ChromaDB 的设置说明。
```
工具输入：
```json
{
"query": "ChromaDB 设置说明",
"top_k": 5
}
```
使用前：
```bash
LOCAL_DOCS_PATH=/绝对路径/到/docs
npm run index
```
### `semantic_code_search`
用于通过含义而不是确切文本查找代码。
提示：
```text
使用 Infimium semantic_code_search 查找价格计算逻辑。
```
工具输入：
```json
{
"query": "价格计算逻辑",
"language": "typescript",
"top_k": 5
}
```
`language` 是可选的。支持的值取决于索引文件：`javascript`、`typescript`、`python`。
使用前：
```bash
CODEBASE_PATH=/绝对路径/到/code
npm run index
```
### `dep_graph`
用于查看符号的定义位置、谁导入它以及其文件导入的内容。
提示：
```text
使用 Infimium dep_graph 获取 calcPropertyValue。
```
工具输入：
```json
{
"symbol_name": "calcPropertyValue"
}
```
使用前：
```bash
CODEBASE_PATH=/绝对路径/到/code
npm run index
```
### `shell`
用于安全、允许列出的本地命令。
提示：
```text
使用 Infimium shell 运行 git status。
```
工具输入：
```json
{
"command": "git status",
"cwd": "/绝对路径/到/repo",
"timeout": 30
}
```
显式允许命令：
```bash
SHELL_ALLOWLIST=ls,git,npm,npx
```
阻止的模式包括 `rm -rf`、`sudo`、`curl`、`wget`、`eval` 和内联代码执行。
### `plan`
在编辑代码之前使用。它检索语义相关的符号，用依赖关系边丰富它们，并为最安全的实现计划询问本地 LLM。
CLI 干运行：
```bash
npx infimium plan --dry-run "在身份验证端点添加速率限制"
```
生成并写入 `plan.md`：
```bash
npx infimium plan --write "在身份验证端点添加速率限制"
```
工具输入：
```json
{
"task": "在身份验证端点添加速率限制",
"dry_run": false,
"write_plan": true,
"output_path": "plan.md",
"top_k": 5
}
```
使用前：
```bash
npx infimium doctor
npx infimium index
```
使用 `--dry-run` 检查检索的上下文而不调用 LLM。如果上下文不好，请在评估计划质量之前重新索引。
### `status`
从终端使用它来检查本地索引健康状况。
```bash
npm run status
```
### `doctor`
如果设置感觉损坏，请首先使用它。
```bash
npx infimium doctor
```
它按顺序检查：
1. Node/npm 版本兼容性
2. Ollama 已安装并运行
3. `nomic-embed-text` 已拉取
4. ChromaDB 可达
5. `.env` 和所需密钥
6. 当前仓库是否已索引
每个失败的检查都包含一个可复制的修复命令。该命令如果有任何失败，退出状态为 `1`，因此它适用于脚本。
示例输出：
```text
───────────────────────────
Infimium 状态
───────────────────────────
文档 47 文件 · 312 块
代码 847 符号 · 124 文件
依赖图 312 个关系
项目 2 个监视
数据库大小 2.1 MB
上次索引 2 小时前
───────────────────────────
```
## 连接到 Claude Desktop
```json
{
"mcpServers": {
"infimium": {
"command": "npx",
"args": ["infimium", "serve"],
"env": {
"SEARCH_API_KEY": "您的 brave_search_api_key",
"LOCAL_DOCS_PATH": "/绝对路径/到/docs",
"CODEBASE_PATH": "/绝对路径/到/code",
"OLLAMA_HOST": "http://localhost:11434",
"CHROMADB_HOST": "http://localhost:8000"
}
}
}
}
```
## 连接到 Cursor / Windsurf
```json
{
"mcpServers": {
"infimium": {
"command": "npx",
"args": ["infimium", "serve"],
"env": {
"SEARCH_API_KEY": "您的 brave_search_api_key",
"LOCAL_DOCS_PATH": "/绝对路径/到/docs",
"CODEBASE_PATH": "/绝对路径/到/code",
"OLLAMA_HOST": "http://localhost:11434",
"CHROMADB_HOST": "http://localhost:8000"
}
}
}
}
```
## 定价
自托管免费永久（MIT）。需要我们为您运行吗？
infimium.ai — 起始价 $12/月，14 天试用，无免费托管层。
付费托管预览：
- 大型仓库和文档集的管理索引工作器。
- 主机项目内存和 `plan.md` 生成。
- 团队仪表板，用于索引新鲜度、工具使用情况和故障。
- 优先语言/解析器支持。
## 贡献
[CONTRIBUTING.md](CONTRIBUTING.md)
添加新语言？从这里开始。
