# Vending Machine MCP Server

13 specialist AI agents for your coding assistant. Use them from Claude Code, Codex, or any MCP-compatible client.

## Scope

This document describes the `**vending-machine-mcp**` PyPI package: a standalone stdio MCP server. It ships complete and does not depend on any other repository layout.

Source of truth for tools and agents in this package:

- `vending_machine_mcp/mcp_server.py`

## Tools (Current Signatures)


| Tool                  | Signature                                                                                                 | What it does                                                                                |
| --------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `list_agents`         | `list_agents()`                                                                                           | Lists available agent IDs, model, and description                                           |
| `hire_agent`          | `hire_agent(agent_id: str, task: str)`                                                                    | Starts an async agent job and returns `job_id`                                              |
| `check_job`           | `check_job(job_id: str)`                                                                                  | Polls async job status/results                                                              |
| `search_scripts`      | `search_scripts(query: str)`                                                                              | Finds scripts by natural-language query                                                     |
| `run`                 | `run(vending_code: str, user_input: str)`                                                                 | Runs a marketplace script async, returns `job_id`                                           |
| `info`                | `info(vending_code: str)`                                                                                 | Shows script details, validation info, usage, similar scripts                               |
| `run_code`            | `run_code(code: str, language: str = "python", packages: str = "")`                                       | Runs Python/JS code in sandbox                                                              |
| `audit_code`          | `audit_code(code: str)`                                                                                   | Async workflow: Bug Hunter -> Test Goblin -> Code Gremlin                                   |
| `vector_store_add`    | `vector_store_add(collection, text, doc_id="", metadata_json="{}", provider="", model="", dimensions="")` | Embeds text (BYOK) and stores in local SQLite. Optional provider/model/dimensions override. |
| `vector_store_search` | `vector_store_search(collection, query, limit=5, provider="", model="", dimensions="")`                   | Semantic search (auto-detects provider/model from collection)                               |
| `vector_store_list`   | `vector_store_list(collection="", limit=50)`                                                              | Lists collections, or documents inside one collection                                       |
| `query_knowledge`     | `query_knowledge(collection, question, limit=5, provider="", model="", dimensions="")`                    | RAG: retrieves chunks then LLM answers. Auto-detects embedding config.                      |


## Async Behavior

- `hire_agent`, `run`, and `audit_code` return a `job_id`.
- Use `check_job(job_id)` to retrieve final output.

## Agents (Current Registry)


| Agent ID           | Name             | What it does                                                                                                                                                                                        |
| ------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bug-hunter`       | Bug Hunter       | Code review, debugging, and security audits                                                                                                                                                         |
| `cloud-sensei`     | Cloud Sensei     | AWS architecture review, troubleshooting, cost optimization                                                                                                                                         |
| `code-gremlin`     | Code Gremlin     | Code writing, debugging, and refactoring                                                                                                                                                            |
| `data-sprite`      | Data Sprite      | DB schemas, migrations, seed data, ETL scripts                                                                                                                                                      |
| `desk-pilot`       | Desk Pilot       | Admin support: email drafts, SOPs, meeting/task prep                                                                                                                                                |
| `devops-dwarf`     | DevOps Dwarf     | Docker, Terraform, CI/CD, Kubernetes, deployment assets                                                                                                                                             |
| `embeddings-agent` | Embeddings Agent | Embeds text, persists vectors to the local store, and analyzes similarity. After the job finishes, query with `query_knowledge`. Needs one of: OpenAI, Voyage AI, or Gemini keys (see Requirements) |
| `inbox-zero`       | Inbox Zero       | Email triage, categorization, prioritization, draft replies                                                                                                                                         |
| `mcp-maker`        | MCP Maker        | MCP server scaffolding and tool definitions                                                                                                                                                         |
| `number-crunch`    | Number Crunch    | Data analysis, trends, KPI reporting                                                                                                                                                                |
| `pdf-forge`        | PDF Forge        | Structured PDF/report generation                                                                                                                                                                    |
| `test-goblin`      | Test Goblin      | Unit/integration/e2e test generation                                                                                                                                                                |
| `vibe-writer`      | Vibe Writer      | Content drafting: posts, newsletters, messaging                                                                                                                                                     |


## Quick Start

```bash
pip install vending-machine-mcp
```

### Claude Code / Codex / Any MCP Client

```json
{
  "mcpServers": {
    "vending-machine": {
      "command": "vending-machine-mcp"
    }
  }
}
```

### Usage

```text
> hire_agent("bug-hunter", "Review this auth middleware for vulnerabilities: <paste code>")
> check_job("abc123")
> run("S-7K2M", "input payload")
> audit_code("<paste code>")
> vector_store_add("my-kb", "Full note text...", metadata_json='{"source":"notes.md"}')
> vector_store_search("my-kb", "How do we deploy?")
> query_knowledge("my-kb", "Summarize the deployment process")
```

### Embed and query flow (embeddings-agent + query_knowledge)

```text
> hire_agent("embeddings-agent", "Embed my API docs: <paste text>")
> check_job("job-id")
  -> "Stored 24 chunks in collection `embeddings-api-docs-txt`.
      Query with: query_knowledge(collection='embeddings-api-docs-txt', question='...')"
> query_knowledge("embeddings-api-docs-txt", "How does authentication work?")
  -> "Based on the documents: Authentication uses JWT tokens issued by... [1] [3]"
```

### What works out of the box

After `pip install` and pointing your MCP client at `vending-machine-mcp`, you do **not** need a separate database or vector service. Several tools are useful **with no API keys at all**:

- `**list_agents`** — lists agents (starting a run still needs OpenRouter; see Requirements).
- `**search_scripts`** — natural-language search over bundled marketplace scripts using a **local SQLite index** and **deterministic local embeddings** when no embedding provider key is set. Results are real and ranked; quality is **better** if you set `**VOYAGE_API_KEY`** (or OpenAI / Gemini — same priority as below).
- `**info`** — script details from the in-memory store; **similar scripts** / **chain hints** use the same SQLite index when available.
- `**vector_store_add` / `vector_store_search` / `vector_store_list`** — personal collections in another local SQLite file; same **local hash** fallback without keys.
- `**query_knowledge`** — RAG over any collection: retrieves context chunks then asks an LLM to answer. Requires at least one LLM key (`**OPENROUTER_API_KEY`**, `**OPENAI_API_KEY`**, or `**GEMINI_API_KEY**`) for the answer step; embedding search itself works with local hash when no embedding key is set.

Anything that **calls models** (`hire_agent`, `check_job` results, `audit_code`) needs `**OPENROUTER_API_KEY`**. Anything that runs code (`run`, `run_code`, sandbox paths inside agents) needs a sandbox key (`DAYTONA_API_KEY` or `E2B_API_KEY`). The `**embeddings-agent`** expects at least one embedding provider key (see Requirements). No extra setup steps beyond env vars and MCP config.

### Marketplace script search (`search_scripts`)

- Implemented in `vending_machine_mcp/graph.py`: a **SQLite script index** with semantic search over embedded script text. No external graph or vector database service is required.
- Default DB: `~/.local/share/vending-machine-mcp/script_index.sqlite3` (or `$XDG_DATA_HOME/vending-machine-mcp/…`). Override with `**SCRIPT_INDEX_DB_PATH`**.
- Embeddings for indexing and queries use **Voyage voyage-code-3** (document/query types) when `**VOYAGE_API_KEY`** is set; otherwise **OpenAI** → **Gemini** → deterministic **local hash**, same idea as the vector store. Only rows whose stored vector length matches the query embedding are ranked (avoid mixing providers without re-seeding or clearing the DB).

### Local vector store

- Default DB path: `~/.local/share/vending-machine-mcp/vector_store.sqlite3` (or `$XDG_DATA_HOME/vending-machine-mcp/…`). Override with `**VECTOR_STORE_DB`**.
- Uses the same embedding key priority as `vector_store_add`: **Voyage → OpenAI → Gemini → deterministic local hash**. Override with `**EMBEDDING_PROVIDER`** / `**EMBEDDING_MODEL`** / `**EMBEDDING_DIMENSIONS**` env vars, or pass `provider`/`model`/`dimensions` directly to each tool call.
- The **provider** and **model** used are stored per-document. When searching or querying, the tool auto-detects which provider/model the collection uses and embeds the query the same way.

### `OPENAI_API_KEY`: what it does (and what it does not)

`OPENAI_API_KEY` is for OpenAI’s **Embeddings API** (`text-embedding-3-small`) wherever the package needs vectors. It is **not** a substitute for `**OPENROUTER_API_KEY`**, which is what runs the LLM inside agents (including `**embeddings-agent`**).

With `**OPENAI_API_KEY**` set (and no `**VOYAGE_API_KEY**`, which takes priority):

- `**search_scripts**` — better semantic search over the marketplace script index (same key used when seeding/indexing scripts).
- `**vector_store_add` / `vector_store_search**` — embeddings for your personal collections (plus `**vector_store_list**` to inspect them).

There is **no MCP tool that runs raw SQL**. Your chat app talks to the two local SQLite files **only through tools**: use `**search_scripts`** for bundled scripts, and `**vector_store_search`** / `**query_knowledge`** / `**vector_store_list**` for data you added with `**vector_store_add**` or the `**embeddings-agent**`.

`**embeddings-agent**`: call `**hire_agent("embeddings-agent", …)**` then `**check_job**`. The agent now **persists** all chunks + vectors into the vector store under a named collection. Use `**query_knowledge(collection, question)`** afterward to ask questions about that data. The agent graph needs `**OPENROUTER_API_KEY`**; the embedding steps need at least one embedding key (`**OPENAI_API_KEY`** / Voyage / Gemini); `**query_knowledge**` needs at least one LLM key (OpenRouter, OpenAI, or Gemini) for the answer step.

## Requirements

- Python 3.11+
- `**OPENROUTER_API_KEY**` — required to **run** agents (`hire_agent`, `audit_code`, and any tool that executes an LLM workflow). Not required only to **list** agents or to use search / vector store without agents.
- **Sandbox** — required for `**run`**, `**run_code`**, and code execution inside agents: set `**DAYTONA_API_KEY**` or `**E2B_API_KEY**`. The server picks a provider when both exist; set `**SANDBOX_PROVIDER=daytona**` or `**SANDBOX_PROVIDER=e2b**` to force one.
- `**embeddings-agent**` — same as other agents: `**OPENROUTER_API_KEY**` is required to **run** it via `**hire_agent`**. For embedding operations inside that agent, use at least one of `**OPENAI_API_KEY`**, `**VOYAGE_API_KEY**`, or `**GEMINI_API_KEY**` (`**GOOGLE_API_KEY**` is an alias for Gemini).

Optional for **better** (not required for **working**) semantic search and vector store **without** using `**embeddings-agent`**: the same embedding keys. Priority is **Voyage → OpenAI → Gemini → local hash** (see sections above).

Environment variables can be set in the shell that launches the MCP server or in a `**.env`** file in the server’s working directory (the package loads it on startup).