Metadata-Version: 2.4
Name: retrieval-mcp
Version: 0.2.2
Summary: Installable MCP server for the Retrieval API: academic-paper search + journal memory + ACE playbook + semantic code search
Project-URL: Homepage, https://retrieval.rnarket.com
License: MIT
Keywords: ace,code-search,llm,mcp,model-context-protocol,papers,retrieval,search
Requires-Python: >=3.10
Requires-Dist: astchunk>=0.1.0
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2.0
Requires-Dist: tree-sitter-language-pack>=1.12
Requires-Dist: tree-sitter>=0.23
Description-Content-Type: text/markdown

# retrieval-mcp

An **MCP server** for the Retrieval academic-paper API — semantic paper search,
document matching, ACE journal memory, and index inventory. Self-contained: it talks
to the backend over HTTP only (just `mcp` + `httpx`), so it installs anywhere with
`uvx` / `pip` — no repo checkout, no GPU, no models.

By default it targets the compute box on the lab LAN (`http://10.100.100.111:8000`),
which trusts LAN callers so **no key is needed**. Off-LAN, point `RETRIEVAL_API_URL` at
the public gateway (`https://retrieval.rnarket.com`) and set `RETRIEVAL_API_KEY` (`sk-...`).

## Tools

Every tool's full docstring (purpose + each argument with its default + an example)
is what your LLM sees — call them by name. Summary:

**Paper retrieval**

| Tool | What it does |
|------|--------------|
| `search_papers` | Semantic hybrid search over 95k+ top-venue CS papers (filters: `venue`, `year`, `title_only`) |
| `search_within_paper` | Every matching passage inside one paper |
| `match_document` / `match_paper` | Content-nearest papers to a passage / to a paper |
| `list_conferences` / `corpus_stats` | Venue registry / corpus size |

**Journal work-memory** (scoped to the current project by default)

| Tool | What it does |
|------|--------------|
| `journal_record` | Record a work note (`memory`) or a file's current content (`doc`, latest-wins) |
| `journal_search` | Search memory — `keyword` (FTS5, no embedding) or `hybrid`/`dense`/`sparse` |
| `journal_recent` | List recent entries |
| `journal_index_dir` | Batch-index a local dir's files into the journal (latest-wins per file) |

**Code KB** (source stays local — only chunks are uploaded)

| Tool | What it does |
|------|--------------|
| `index_code` | AST-chunk a repo locally (40+ languages) and index it, scoped to you |
| `search_code` | Semantic code search with `path:line` citations |
| `index_inventory` | Your indexed-file tree: user → host → project → dir → file |

**ACE playbook** (accumulated, curated lessons per project)

| Tool | What it does |
|------|--------------|
| `ace_context_aware` / `ace_playbook` | Retrieve relevant / list all curated bullets |
| `ace_enhance_prompt` / `ace_smart_generate` | Attach playbook lessons to a prompt (no LLM call) |
| `ace_smart_reflect` | Curate a transferable lesson into the playbook (grow-and-refine dedup) |

### Code KB language coverage

`index_code` chunks 40+ languages structurally via tree-sitter (cAST): Python,
TypeScript/TSX/JS/JSX (React), Java, Kotlin (incl. Jetpack Compose `.kt`/`.kts`),
Swift, Go, Rust, C/C++, C#, Ruby, PHP, Lua, Scala, Dart, R, Julia, Elixir, Erlang,
Haskell, OCaml, SQL, GraphQL, Protobuf, HTML, CSS/SCSS (Tailwind = CSS classes),
Vue, Svelte, shell, PowerShell, Dockerfile, Terraform/HCL, CMake, YAML/JSON/TOML/XML,
and more. Grammarless config/text files fall back to line-window chunks; docs (`.md`)
and binaries are skipped (docs belong in the journal via `journal_index_dir`).

## Install

### Claude Code

```bash
# LAN (no key):
claude mcp add retrieval -- uvx retrieval-mcp
# Off-LAN (public gateway + key):
claude mcp add retrieval \
  --env RETRIEVAL_API_URL=https://retrieval.rnarket.com \
  --env RETRIEVAL_API_KEY=sk-... \
  -- uvx retrieval-mcp
```

### Claude Desktop / any MCP client

`claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`,
Windows: `%APPDATA%\Claude\`):

```json
{
  "mcpServers": {
    "retrieval": {
      "command": "uvx",
      "args": ["retrieval-mcp"],
      "env": {
        "RETRIEVAL_API_URL": "https://retrieval.rnarket.com",
        "RETRIEVAL_API_KEY": "sk-...",
        "JOURNAL_PROJECT_SLUG": "my-project"
      }
    }
  }
}
```

No `uv`? `pip install retrieval-mcp` then use `"command": "retrieval-mcp"`.

## Config (env)

| Var | Default | Notes |
|-----|---------|-------|
| `RETRIEVAL_API_URL` | `http://10.100.100.111:8000` | LAN compute box (no key). Off-LAN, set to `https://retrieval.rnarket.com`. |
| `RETRIEVAL_API_KEY` | — | `sk-...` key for the gateway (create under `/auth/keys`). Required off-LAN. |
| `JOURNAL_PROJECT_SLUG` | current dir name | Journal namespace; scopes journal reads/writes so projects don't leak into each other. |

## License

MIT
