Metadata-Version: 2.4
Name: certainlogic-mcp
Version: 0.4.0
Summary: Community cache & private AI for your IDE agent. Plugs into Cursor, Claude Code, VS Code, JetBrains.
Author-email: CertainLogic <hello@certainlogic.ai>
License-Expression: MIT
Project-URL: Homepage, https://certainlogic.ai/mcp
Project-URL: Source, https://github.com/certainlogic/certainlogic-mcp
Keywords: mcp,cache,brain,ai,certainlogic
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.27.0
Requires-Dist: httpx>=0.27.0

# CertainLogic Brain MCP

**Community cache & private AI for developers on the FIAS gig economy.**

Plug into Cursor, Claude Code, VS Code, or JetBrains. Every cached query makes AI cheaper for everyone. Pro tier gives you your own private memory and audit trail.

---

## 🔥 OpenRouter 30% Off — Wrapped In

Every cache miss routes through OpenRouter with **30% off** the standard model rate. Brain MCP negotiates it automatically — you don't need a coupon or enterprise deal. Cache hits are free anyway.

**This is the hook:** Your agent gets cheaper on every uncached query. Cache hits are free. Win-win.

---

## Quick Install (5 minutes)

### 1. Install the package

```bash
pip install certainlogic-mcp
```

> **PyPI package is ready.** No npm needed — Python projects install via pip.

Or install from source:

```bash
git clone https://github.com/CertainLogicAI/certainlogic-mcp.git
cd certainlogic-mcp
pip install -e .
```

### 2. Set your API key

Brain MCP routes cache misses through OpenRouter. You need an API key.

```bash
export OPENROUTER_API_KEY="sk-or-..."
```

**Don't have one?** [Get a free OpenRouter key](https://openrouter.ai/keys) (takes 30 seconds). Free models are available — you pay only if you need faster ones.

### 3. Run the setup wizard

```bash
python3 -m certainlogic_mcp.server setup
```

Or if the shortcut is installed:

```bash
certainlogic-mcp setup
```

This writes your editor's MCP config automatically.

### 4. Restart your editor

Cursor, VS Code, and JetBrains auto-detect MCP servers on restart. Claude Code detects it on next `claude` command.

### 5. Done

Your agent now routes through Brain MCP. Every query checks the community cache first. Cache hit → instant, zero cost. Cache miss → routes to cheapest model, stores for next time.

---

## Manual Config (if the wizard doesn't work)

Your editor reads `mcp.json` from its config directory. Here's what to add:

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "certainlogic-mcp": {
      "command": "python3",
      "args": ["-m", "certainlogic_mcp.server"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}
```

### VS Code

Add to `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "certainlogic-mcp": {
      "command": "python3",
      "args": ["-m", "certainlogic_mcp.server"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}
```

### Claude Code

Add to `~/.claude/servers.json`:

```json
{
  "mcpServers": {
    "certainlogic-mcp": {
      "command": "python3",
      "args": ["-m", "certainlogic_mcp.server"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}
```

### JetBrains

Go to **Settings → Tools → MCP Server**, add a new server:

- **Name:** `certainlogic-mcp`
- **Command:** `python3 -m certainlogic_mcp.server`
- **Environment variables:** `OPENROUTER_API_KEY=sk-or-...`

---

## What You Get

### Free Tier (Community Cache)

Everyone shares a community cache. When you ask a question, the cache checks if someone already asked it. If yes → instant response, zero cost. If no → routes to a model, stores the result, everyone benefits next time.

| Tool | What It Does |
|------|-------------|
| `cache_query` | Check community cache. Miss → route to model → store. |
| `cache_stats` | See how many tokens the community saved. |

### Pro Tier ($49/mo — Private AI)

Your own private cache and full Brain OS memory. Nothing shared. Ever.

| Tool | What It Does |
|------|-------------|
| `private_query` | Personal cache. Your queries never leave your control. |
| `brain_search` | Search your persistent knowledge graph across sessions. |
| `brain_get` | Retrieve any fact or page from memory. |
| `brain_stats` | Memory usage, facts stored, cache performance. |

---

## Pro License

Get a license key:

```bash
certainlogic-mcp setup --key YOUR_LICENSE_KEY
```

Or set the environment variable:

```bash
export BRAIN_MCP_LICENSE="YOUR_LICENSE_KEY"
```

The server validates the key and unlocks Pro tools automatically.

**Need a key?** Email `hello@certainlogic.ai` or open an issue on GitHub.

---

## Running the License Server (Self-Hosted)

If you want to run your own license validation server:

```bash
python3 -m certainlogic_mcp.license_server
```

Default port: 8899. Configure with:

```bash
export LICENSE_PORT=8899
export BRAIN_MCP_LICENSE_SERVER="http://your-server:8899"
```

---

## Cache Location

By default, the cache lives at `/tmp/brain-mcp-cache/`. Change it:

```bash
export BRAIN_MCP_CACHE_DIR="$HOME/.brain-mcp-cache"
```

- **Free tier:** `community.db` (shared, anonymized)
- **Pro tier:** `personal_YOURHASH16.db` (isolated per license)

---

## Docker

Run the full stack with Docker Compose:

```bash
# Clone the repo
git clone https://github.com/CertainLogicAI/certainlogic-mcp.git
cd certainlogic-mcp

# Start MCP server + license server
docker compose up

# Or build and run individually:
docker build -t certainlogic/mcp-server .
docker build -f Dockerfile.license -t certainlogic/license-server .

docker run -d --name license-server -p 8899:8899 certainlogic/license-server
docker run -it --rm --name mcp-server \
  -e BRAIN_MCP_LICENSE_SERVER=http://license-server:8899 \
  -e OPENROUTER_API_KEY=sk-or-... \
  certainlogic/mcp-server
```

## Architecture

```
Your IDE (Cursor/VS Code/etc)
       │
       │ MCP protocol (stdio)
       ▼
Brain MCP Server
       │
       ├── Cache check (SQLite)
       │     ├── Hit → return instantly
       │     └── Miss → route to model
       │
       ├── OpenRouter (free/paid models)
       │
       └── [Pro tier] Brain OS API (port 8000)
             ├── Knowledge graph search
             ├── Fact retrieval
             └── Persistent memory
```

---

## Troubleshooting

### "mcp: command not found" or "certainlogic-mcp not found"

Make sure the package is installed:

```bash
pip install certainlogic-mcp
python3 -m certainlogic_mcp.server --help
```

### "Cache miss is slow"

First query to a new topic takes 5-30 seconds depending on the model. Every subsequent identical query is instant.

### "OpenRouter API key not set"

```bash
export OPENROUTER_API_KEY="sk-or-..."
```

Or add it to your editor's MCP config env vars.

### Server won't start

Check the logs:

```bash
python3 -m certainlogic_mcp.server 2>&1
```

---

## Links

- **Website:** [certainlogic.ai/mcp](https://certainlogic.ai/mcp)
- **GitHub:** [github.com/CertainLogicAI/certainlogic-mcp](https://github.com/CertainLogicAI/certainlogic-mcp)
- **X:** [@CertainLogicAI](https://x.com/CertainLogicAI)
- **Email:** hello@certainlogic.ai
