Metadata-Version: 2.4
Name: zettaquant-vslm-mcp
Version: 0.1.0
Summary: MCP server that exposes ZettaQuant V-SLM (topic-conditioned sentence relevancy) to any MCP-aware LLM host — Claude Desktop, Cursor, Zed, Windsurf.
Project-URL: Homepage, https://zettaquant.ai
Project-URL: Documentation, https://github.com/zettaquant/zettaquant-vslm-mcp
Project-URL: Source, https://github.com/zettaquant/zettaquant-vslm-mcp
Project-URL: Issues, https://github.com/zettaquant/zettaquant-vslm-mcp/issues
Author-email: ZettaQuant <support@zettaquant.ai>
License: MIT
License-File: LICENSE
Keywords: claude,cursor,llm,mcp,model-context-protocol,tools,vslm,zettaquant
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Description-Content-Type: text/markdown

# zettaquant-vslm-mcp

**MCP server that exposes ZettaQuant V-SLM to any MCP-aware LLM host.**

Add three lines to your Claude Desktop / Cursor / Zed / Windsurf config and your model can autonomously filter noisy context (earnings-call transcripts, news articles, long reports, log lines) using ZettaQuant's topic-conditioned relevancy classifier — typically cutting token spend 5-10× before the LLM even sees the input.

---

## What it exposes

One tool, over stdio, via the [Model Context Protocol](https://modelcontextprotocol.io):

| Tool | Purpose |
|---|---|
| `vslm_predict(sentences, query)` | Filter `sentences` to only those relevant to `query`. Returns `relevant_sentences` plus stats. Uses the broad-domain V-SLM `general_context_agent` under the hood. |

The LLM decides when to call it on its own — no code you have to write in the host.

---

## Install & configure

You need a ZettaQuant API key with the `vslm` scope. Get one at [zettaquant.ai](https://zettaquant.ai) (or ask your account contact).

### Claude Desktop

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

```json
{
  "mcpServers": {
    "zettaquant-vslm": {
      "command": "uvx",
      "args": ["zettaquant-vslm-mcp"],
      "env": {
        "ZQ_API_KEY": "<your api key>"
      }
    }
  }
}
```

Restart Claude Desktop. The tools appear under the "Tools" menu.

### Cursor

Edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "zettaquant-vslm": {
      "command": "uvx",
      "args": ["zettaquant-vslm-mcp"],
      "env": { "ZQ_API_KEY": "<your api key>" }
    }
  }
}
```

Restart Cursor.

### Zed

In `~/.config/zed/settings.json`:

```json
{
  "context_servers": {
    "zettaquant-vslm": {
      "command": {
        "path": "uvx",
        "args": ["zettaquant-vslm-mcp"],
        "env": { "ZQ_API_KEY": "<your api key>" }
      }
    }
  }
}
```

### Windsurf / other MCP hosts

Any host that supports the standard `mcpServers` config shape works — use the same `command` + `args` + `env` block as above.

---

## Environment variables

| Variable | Required | Default | Notes |
|---|---|---|---|
| `ZQ_API_KEY` | ✅ | — | Your ZettaQuant API key. Must have the `vslm` scope. |
| `ZQ_BASE_URL` | | `https://api.zettaquant.ai` | Override for staging or a private gateway. |

---

## Usage examples in the LLM

Once installed, just ask naturally. Some prompts that will trigger `vslm_predict`:

- *"Here are 40 sentences from Apple's Q3 earnings call. Pull out the ones about AI capex plans."*
- *"Filter these log lines down to anything related to lateral movement."*
- *"I pasted a 10-K risk section. Only show me sentences about supply-chain exposure."*

The model calls `vslm_predict` under the hood, gets back the relevant sentences, and works from those — cheaper and more precise than reading the full input.

---

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard (released by Anthropic, November 2024) for connecting LLM hosts to external tools and data. It's essentially "USB-C for AI apps" — write one integration and every MCP-aware host can use it. This package is a **server** in MCP parlance; the LLM host is the **client**.

---

## Development

```bash
uv venv
uv pip install -e ".[dev]"
export ZQ_API_KEY="..."
python -m zettaquant_vslm_mcp
```

The server speaks JSON-RPC on stdin/stdout. To poke it manually, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npx @modelcontextprotocol/inspector uvx zettaquant-vslm-mcp
```

---

## Troubleshooting

- **"ZQ_API_KEY is not set"** in the host logs → the `env` block in your MCP config didn't propagate. Confirm the config file path and restart the host.
- **401 in tool output** → key is valid but wrong. Try it directly: `curl -H "x-api-key: $ZQ_API_KEY" https://api.zettaquant.ai/v1/usage/me`.
- **403 SCOPE_DENIED** → your key doesn't have the `vslm` scope. Contact ZettaQuant.
- **429 QUOTA_EXCEEDED** → you hit your per-period cap; the error message includes the reset time.

---

## License

MIT.
