# Infimium Agent

> Infimium helps agents find the right code, docs, and dependencies — before they edit. Local-first, open-source, MCP-compatible.

- **Type:** MCP server
- **Install:** `agentstack add mcp-infimium-ai-infimium-agent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [infimium-ai](https://agentstack.voostack.com/s/infimium-ai)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [infimium-ai](https://github.com/infimium-ai)
- **Source:** https://github.com/infimium-ai/infimium-agent
- **Website:** https://infimium.com

## Install

```sh
agentstack add mcp-infimium-ai-infimium-agent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Private search MCP for AI agents. Web · code · local docs · dependency graph — one endpoint, your machine.

[](https://www.npmjs.com/package/infimium)
[](LICENSE)
[](https://github.com/infimium-ai/infimium-agent)

## The problem

Agents need precise context, but large repos make that expensive fast.
Keyword search is brittle: it misses intent, aliases, and the symbols that actually matter.

```
200,000 lines of code
Agent reads everything → 💀 context blown + $$$
grep "price calculation" → misses calcPropertyValue()
```

## With Infimium

Infimium indexes your docs, code symbols, and dependency graph locally.
Agents ask focused tools for the right context instead of reading the whole project.

```
tool: semantic_code_search
query: "price calculation logic"

→ services/property/calc.ts:142 · calcPropertyValue()
→ imported by: listing.ts, tax.ts, pdf-generator.ts, calc.test.ts
```

## Tools

`web_search` — Brave web search with retry and concise source snippets.

`fetch_url` — fetches HTML, strips noise, returns Markdown or text.

`query_local_docs` — local document RAG over `.md`, `.txt`, `.html`, and `.pdf`.

`semantic_code_search` — differentiator: tree-sitter symbols + local embeddings for meaning-based code search.

`dep_graph` — differentiator: SQLite import graph for "where is this defined and who imports it?"

`shell` — allowlisted command runner with blocked patterns, timeout, and output caps.

`plan` — differentiator: retrieves semantic code context and dependency edges, then drafts an implementation plan.

`status` — CLI health check for indexed docs, code symbols, dep graph relationships, watched projects, DB size, and last index time.

`doctor` — CLI setup check for Node/npm, Ollama, ChromaDB, `.env`, and index readiness.

## Why self-hosted

Your code index, your embeddings, your dep graph — all on your machine. Nothing leaves.

- Embeddings run locally with Ollama.
- No vendor lock-in: MCP, SQLite, ChromaDB, TypeScript.
- Works in air-gapped environments.

## Quick start

```bash
git clone https://github.com/infimium/infimium && cd infimium
cp .env.example .env  # add your SEARCH_API_KEY
./scripts/setup.sh
```

## Setup guide

### npm package

Requires Node.js 22.5+.

Install:

```bash
npm i infimium
```

Create `.env`:

```bash
cp .env.example .env
```

Configure:

```bash
SEARCH_API_KEY=your_brave_api_key
SEARCH_PROVIDER=brave
LOCAL_DOCS_PATH=/absolute/path/to/docs
CODEBASE_PATH=/absolute/path/to/code
OLLAMA_HOST=http://localhost:11434
CHROMADB_HOST=http://localhost:8000
SHELL_ALLOWLIST=ls,git,npm,npx
```

Start Ollama:

```bash
ollama serve
ollama pull nomic-embed-text
```

Start ChromaDB on `http://localhost:8000`:

```bash
chroma run --path ./chroma_db --host localhost --port 8000
```

Or with Docker:

```bash
docker run -p 8000:8000 -v ./chroma_db:/chroma/chroma chromadb/chroma
```

Index docs and code:

```bash
npx infimium index
```

Check status:

```bash
npx infimium status
```

Check setup health:

```bash
npx infimium doctor
```

Generate a grounded implementation plan:

```bash
npx infimium plan --dry-run "add rate limiting to the auth endpoint"
npx infimium plan --write "add rate limiting to the auth endpoint"
```

Serve MCP:

```bash
npx infimium serve
```

`infimium status` is not hardcoded. It reads local SQLite metadata and ChromaDB counts. If it shows `0 files`, run `npx infimium index` after setting `LOCAL_DOCS_PATH` and `CODEBASE_PATH`.

### Docker

```bash
cp .env.example .env
```

Set:

```bash
SEARCH_API_KEY=...
LOCAL_DOCS_PATH=./docs
CODEBASE_PATH=./code
```

Run:

```bash
./scripts/setup.sh
```

The setup script starts ChromaDB, starts Infimium, pulls `nomic-embed-text`, runs indexing, and prints the MCP config.

### Local development

Install dependencies:

```bash
npm install
```

Requires Node.js 22.5+.

Start Ollama:

```bash
ollama serve
ollama pull nomic-embed-text
```

Start ChromaDB on `http://localhost:8000`.

Create `.env`:

```bash
cp .env.example .env
```

Use local paths:

```bash
LOCAL_DOCS_PATH=/absolute/path/to/docs
CODEBASE_PATH=/absolute/path/to/code
OLLAMA_HOST=http://localhost:11434
CHROMADB_HOST=http://localhost:8000
```

Index:

```bash
npm run index
```

Serve:

```bash
npm start -- serve
```

Check status:

```bash
npm run status
```

Check setup:

```bash
npm run doctor
```

Plan a code change:

```bash
npm run plan -- --dry-run "add rate limiting to the auth endpoint"
```

## Tool brief

| Tool | Input | Requires | Output |
| --- | --- | --- | --- |
| `web_search` | `query`, `max_results` | Brave API key | ranked web results |
| `fetch_url` | `url`, `extract` | network access | cleaned Markdown/text |
| `query_local_docs` | `query`, `top_k` | indexed docs, Ollama, ChromaDB | matching document chunks |
| `semantic_code_search` | `query`, `language`, `top_k` | indexed code, Ollama, ChromaDB | matching symbols with file and line range |
| `dep_graph` | `symbol_name` | indexed code graph | definition file, importers, imports |
| `shell` | `command`, `cwd`, `timeout` | allowlisted command | stdout, stderr, exit code |
| `plan` | `task`, `dry_run`, `write_plan`, `output_path`, `top_k`, `language` | indexed code, Ollama, ChromaDB | implementation plan or retrieved context |
| `status` | none | local SQLite/ChromaDB state | index health summary |
| `doctor` | none | local environment | setup pass/fail report |

## Use the tools

After adding Infimium to Claude Desktop, Cursor, or Windsurf, ask the agent to use a specific Infimium tool by name. The MCP client sends the JSON input to Infimium; you do not call these tools with HTTP.

### `web_search`

Use it for current web results.

Prompt:

```text
Use Infimium web_search to find recent MCP server examples.
```

Tool input:

```json
{
  "query": "recent MCP server examples",
  "max_results": 5
}
```

Requires:

```bash
SEARCH_API_KEY=...
SEARCH_PROVIDER=brave
```

### `fetch_url`

Use it to fetch a page and extract readable content.

Prompt:

```text
Use Infimium fetch_url to fetch https://modelcontextprotocol.io and summarize it.
```

Tool input:

```json
{
  "url": "https://modelcontextprotocol.io",
  "extract": "markdown"
}
```

`extract` can be `markdown` or `text`.

### `query_local_docs`

Use it after indexing local documents.

Prompt:

```text
Use Infimium query_local_docs to find setup instructions for ChromaDB.
```

Tool input:

```json
{
  "query": "ChromaDB setup instructions",
  "top_k": 5
}
```

Before using:

```bash
LOCAL_DOCS_PATH=/absolute/path/to/docs
npm run index
```

### `semantic_code_search`

Use it to find code by meaning instead of exact text.

Prompt:

```text
Use Infimium semantic_code_search to find the price calculation logic.
```

Tool input:

```json
{
  "query": "price calculation logic",
  "language": "typescript",
  "top_k": 5
}
```

Before using:

```bash
CODEBASE_PATH=/absolute/path/to/code
npm run index
```

`language` is optional. Supported values depend on indexed files: `javascript`, `typescript`, `python`.

### `dep_graph`

Use it to see where a symbol is defined, who imports it, and what its file imports.

Prompt:

```text
Use Infimium dep_graph for calcPropertyValue.
```

Tool input:

```json
{
  "symbol_name": "calcPropertyValue"
}
```

Before using:

```bash
CODEBASE_PATH=/absolute/path/to/code
npm run index
```

### `shell`

Use it for safe, allowlisted local commands.

Prompt:

```text
Use Infimium shell to run git status.
```

Tool input:

```json
{
  "command": "git status",
  "cwd": "/absolute/path/to/repo",
  "timeout": 30
}
```

Allow commands explicitly:

```bash
SHELL_ALLOWLIST=ls,git,npm,npx
```

Blocked patterns include `rm -rf`, `sudo`, `curl`, `wget`, `eval`, and inline code execution.

### `plan`

Use it before editing code. It retrieves semantically relevant symbols, enriches them with dependency edges, and asks the local LLM for a safest-first implementation plan.

CLI dry run:

```bash
npx infimium plan --dry-run "add rate limiting to the auth endpoint"
```

Generate and write `plan.md`:

```bash
npx infimium plan --write "add rate limiting to the auth endpoint"
```

Tool input:

```json
{
  "task": "add rate limiting to the auth endpoint",
  "dry_run": false,
  "write_plan": true,
  "output_path": "plan.md",
  "top_k": 5
}
```

Before using:

```bash
npx infimium doctor
npx infimium index
```

Use `--dry-run` to inspect retrieved context without calling the LLM. If the context is bad, re-index before judging plan quality.

### `status`

Use it from the terminal to inspect local index health.

```bash
npm run status
```

### `doctor`

Use it first when setup feels broken.

```bash
npx infimium doctor
```

It checks, in order:

1. Node/npm version compatibility
2. Ollama installed and running
3. `nomic-embed-text` pulled
4. ChromaDB reachable
5. `.env` and required keys
6. whether the current repo has been indexed

Every failed check includes one copy-pasteable fix command. The command exits `1` if anything fails, so it works in scripts.

Example output:

```text
───────────────────────────
  Infimium status
───────────────────────────
  Docs         47 files · 312 chunks
  Code         847 symbols · 124 files
  Dep graph    312 relationships
  Projects     2 watched
  DB size      2.1 MB
  Last indexed 2 hours ago
───────────────────────────
```

## Connect to Claude Desktop

```json
{
  "mcpServers": {
    "infimium": {
      "command": "npx",
      "args": ["infimium", "serve"],
      "env": {
        "SEARCH_API_KEY": "your_brave_search_api_key",
        "LOCAL_DOCS_PATH": "/absolute/path/to/docs",
        "CODEBASE_PATH": "/absolute/path/to/code",
        "OLLAMA_HOST": "http://localhost:11434",
        "CHROMADB_HOST": "http://localhost:8000"
      }
    }
  }
}
```

## Connect to Cursor / Windsurf

```json
{
  "mcpServers": {
    "infimium": {
      "command": "npx",
      "args": ["infimium", "serve"],
      "env": {
        "SEARCH_API_KEY": "your_brave_search_api_key",
        "LOCAL_DOCS_PATH": "/absolute/path/to/docs",
        "CODEBASE_PATH": "/absolute/path/to/code",
        "OLLAMA_HOST": "http://localhost:11434",
        "CHROMADB_HOST": "http://localhost:8000"
      }
    }
  }
}
```

## Pricing

Self-host free forever (MIT). Need us to run it for you?

infimium.ai — starts at $12/mo, 14-day trial, no free hosted tier.

Paid hosted glimpse:

- Managed indexing workers for large repos and doc sets.
- Hosted project memory and `plan.md` generation.
- Team dashboards for index freshness, tool usage, and failures.
- Priority language/parser support.

## Contributing

[CONTRIBUTING.md](CONTRIBUTING.md)

Adding a new language? Start here.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [infimium-ai](https://github.com/infimium-ai)
- **Source:** [infimium-ai/infimium-agent](https://github.com/infimium-ai/infimium-agent)
- **License:** MIT
- **Homepage:** https://infimium.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-infimium-ai-infimium-agent
- Seller: https://agentstack.voostack.com/s/infimium-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.