Metadata-Version: 2.4
Name: verbatim-mcp
Version: 0.1.0
Summary: MCP server for querying academic papers via Verbatim RAG
Project-URL: Homepage, https://verbatim.krlabs.eu
Project-URL: Documentation, https://github.com/KRLabsOrg/verbatim-mcp
Project-URL: Repository, https://github.com/KRLabsOrg/verbatim-mcp
Project-URL: Issues, https://github.com/KRLabsOrg/verbatim-mcp/issues
Author-email: KR Labs <info@krlabs.eu>
License-Expression: MIT
License-File: LICENSE
Keywords: academic,claude,mcp,papers,rag,research
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# Verbatim MCP Server

An MCP (Model Context Protocol) server for querying academic papers through [Verbatim](https://verbatim.krlabs.eu) - a RAG system that provides verbatim, cited answers from research papers.

## Features

- **Search papers** by keywords, authors, venues, and years
- **Ask research questions** and get answers with citations
- **Get paper metadata** and full content
- **Export citations** in BibTeX format
- **Browse** authors, venues, and years in the corpus

---

## Quick Start

### Step 1: Get an API Key

1. Go to [verbatim.krlabs.eu](https://verbatim.krlabs.eu)
2. Sign up / Log in
3. Navigate to **Usage** → **API Keys**
4. Create a new API key and copy it

### Step 2: Set up the MCP server

Choose the setup that matches your environment:

---

## Setup for Claude Code (CLI)

**Option A: One-line setup (recommended)**

```bash
claude mcp add --transport stdio \
  --env VERBATIM_API_KEY=vbm_your_key_here \
  verbatim -- uvx verbatim-mcp
```

This uses `uvx` to run the server without installing anything.

**Option B: Install globally first**

```bash
pip install verbatim-mcp

claude mcp add --transport stdio \
  --env VERBATIM_API_KEY=vbm_your_key_here \
  verbatim -- verbatim-mcp
```

**Option C: Config file**

Add to `~/.claude.json` or your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "verbatim": {
      "type": "stdio",
      "command": "uvx",
      "args": ["verbatim-mcp"],
      "env": {
        "VERBATIM_API_KEY": "vbm_your_key_here"
      }
    }
  }
}
```

Then restart Claude Code or run `/mcp` to verify.

---

## Setup for Claude Desktop App

Edit your Claude Desktop config file:

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

```json
{
  "mcpServers": {
    "verbatim": {
      "command": "uvx",
      "args": ["verbatim-mcp"],
      "env": {
        "VERBATIM_API_KEY": "vbm_your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. You should see "verbatim" in the tools menu (hammer icon).

---

## Setup for OpenAI Codex

**Option A: Via CLI**

```bash
codex mcp add verbatim \
  --env VERBATIM_API_KEY=vbm_your_key_here \
  -- uvx verbatim-mcp
```

**Option B: Via config file**

Edit `~/.codex/config.toml`:

```toml
[mcp_servers.verbatim]
command = "uvx"
args = ["verbatim-mcp"]

[mcp_servers.verbatim.env]
VERBATIM_API_KEY = "vbm_your_key_here"
```

Then restart Codex or run `/mcp` to verify.

---

## Setup for Cursor / VS Code with Continue

For **Cursor** or **Continue.dev** extension, add to your config:

```json
{
  "mcpServers": {
    "verbatim": {
      "command": "uvx",
      "args": ["verbatim-mcp"],
      "env": {
        "VERBATIM_API_KEY": "vbm_your_key_here"
      }
    }
  }
}
```

---

## Verify It's Working

In Claude Code, run:
```
/mcp
```

You should see `verbatim` listed with its tools.

Try asking Claude:
> "Use verbatim to search for papers about attention mechanisms"

---

## Available Tools

| Tool | Description |
|------|-------------|
| `query_rag` | Ask a research question, get an answer with citations |
| `verbatim_transform` | Turn any question + context into a verbatim cited answer |
| `search_papers` | Search papers by keywords and filters |
| `get_paper` | Get metadata for a specific paper |
| `get_paper_content` | Get full text of a paper |
| `get_citation` | Get BibTeX citation |
| `list_authors` | Search authors by name |
| `list_venues` | Browse publication venues |
| `list_booktitles` | Browse proceedings/booktitles |
| `list_years` | List available publication years |

## Example Prompts

Once configured, try these with Claude:

- "Search for papers about transformer efficiency from 2023"
- "What does the research say about attention mechanisms?"
- "Find papers by Ashish Vaswani"
- "Get the BibTeX citation for that paper"
- "List the top venues in the corpus"

---

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `VERBATIM_API_KEY` | Your API key (required) | - |
| `VERBATIM_API_URL` | API base URL | `https://verbatim.krlabs.eu` |

---

## Troubleshooting

**"VERBATIM_API_KEY environment variable is required"**
- Make sure you added the `env` block with your API key

**Server not showing in `/mcp`**
- Restart Claude Code: `claude` (exit and reopen)
- Check config syntax: `claude mcp list`

**"API error (401): Unauthorized"**
- Your API key is invalid or expired
- Generate a new one at [verbatim.krlabs.eu/usage](https://verbatim.krlabs.eu/usage)

**"API error (429): Rate limit"**
- You've exceeded your query limit
- Check usage at [verbatim.krlabs.eu/usage](https://verbatim.krlabs.eu/usage)

---

## Compatibility

MCP (Model Context Protocol) is supported by:
- **Claude Code** (CLI) - `~/.claude.json`
- **Claude Desktop App** - `claude_desktop_config.json`
- **OpenAI Codex** - `~/.codex/config.toml`
- **Cursor** - built-in MCP support
- **Continue.dev** - VS Code/JetBrains extension

---

## License

MIT License - see [LICENSE](LICENSE) for details.

## Links

- [Verbatim](https://verbatim.krlabs.eu) - The RAG service
- [MCP Documentation](https://modelcontextprotocol.io) - Learn about MCP
- [Claude Code](https://claude.ai/code) - Claude's coding assistant
