zettaquant-vslm-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- zettaquant_vslm_mcp-0.1.0/.gitignore +33 -0
- zettaquant_vslm_mcp-0.1.0/LICENSE +21 -0
- zettaquant_vslm_mcp-0.1.0/PKG-INFO +167 -0
- zettaquant_vslm_mcp-0.1.0/README.md +142 -0
- zettaquant_vslm_mcp-0.1.0/pyproject.toml +41 -0
- zettaquant_vslm_mcp-0.1.0/src/zettaquant_vslm_mcp/__init__.py +3 -0
- zettaquant_vslm_mcp-0.1.0/src/zettaquant_vslm_mcp/server.py +171 -0
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
*.so
|
|
6
|
+
.Python
|
|
7
|
+
build/
|
|
8
|
+
dist/
|
|
9
|
+
*.egg-info/
|
|
10
|
+
*.egg
|
|
11
|
+
.pytest_cache/
|
|
12
|
+
.ruff_cache/
|
|
13
|
+
.mypy_cache/
|
|
14
|
+
|
|
15
|
+
# Virtual environments
|
|
16
|
+
.venv/
|
|
17
|
+
venv/
|
|
18
|
+
env/
|
|
19
|
+
|
|
20
|
+
# Editors
|
|
21
|
+
.vscode/
|
|
22
|
+
.idea/
|
|
23
|
+
*.swp
|
|
24
|
+
*.swo
|
|
25
|
+
|
|
26
|
+
# OS
|
|
27
|
+
.DS_Store
|
|
28
|
+
Thumbs.db
|
|
29
|
+
|
|
30
|
+
# Secrets — never commit
|
|
31
|
+
.env
|
|
32
|
+
.env.*
|
|
33
|
+
!.env.example
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ZettaQuant
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: zettaquant-vslm-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: MCP server that exposes ZettaQuant V-SLM (topic-conditioned sentence relevancy) to any MCP-aware LLM host — Claude Desktop, Cursor, Zed, Windsurf.
|
|
5
|
+
Project-URL: Homepage, https://zettaquant.ai
|
|
6
|
+
Project-URL: Documentation, https://github.com/zettaquant/zettaquant-vslm-mcp
|
|
7
|
+
Project-URL: Source, https://github.com/zettaquant/zettaquant-vslm-mcp
|
|
8
|
+
Project-URL: Issues, https://github.com/zettaquant/zettaquant-vslm-mcp/issues
|
|
9
|
+
Author-email: ZettaQuant <support@zettaquant.ai>
|
|
10
|
+
License: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: claude,cursor,llm,mcp,model-context-protocol,tools,vslm,zettaquant
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Requires-Dist: httpx>=0.27.0
|
|
23
|
+
Requires-Dist: mcp>=1.2.0
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
|
|
26
|
+
# zettaquant-vslm-mcp
|
|
27
|
+
|
|
28
|
+
**MCP server that exposes ZettaQuant V-SLM to any MCP-aware LLM host.**
|
|
29
|
+
|
|
30
|
+
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.
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## What it exposes
|
|
35
|
+
|
|
36
|
+
One tool, over stdio, via the [Model Context Protocol](https://modelcontextprotocol.io):
|
|
37
|
+
|
|
38
|
+
| Tool | Purpose |
|
|
39
|
+
|---|---|
|
|
40
|
+
| `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. |
|
|
41
|
+
|
|
42
|
+
The LLM decides when to call it on its own — no code you have to write in the host.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Install & configure
|
|
47
|
+
|
|
48
|
+
You need a ZettaQuant API key with the `vslm` scope. Get one at [zettaquant.ai](https://zettaquant.ai) (or ask your account contact).
|
|
49
|
+
|
|
50
|
+
### Claude Desktop
|
|
51
|
+
|
|
52
|
+
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"mcpServers": {
|
|
57
|
+
"zettaquant-vslm": {
|
|
58
|
+
"command": "uvx",
|
|
59
|
+
"args": ["zettaquant-vslm-mcp"],
|
|
60
|
+
"env": {
|
|
61
|
+
"ZQ_API_KEY": "<your api key>"
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Restart Claude Desktop. The tools appear under the "Tools" menu.
|
|
69
|
+
|
|
70
|
+
### Cursor
|
|
71
|
+
|
|
72
|
+
Edit `~/.cursor/mcp.json`:
|
|
73
|
+
|
|
74
|
+
```json
|
|
75
|
+
{
|
|
76
|
+
"mcpServers": {
|
|
77
|
+
"zettaquant-vslm": {
|
|
78
|
+
"command": "uvx",
|
|
79
|
+
"args": ["zettaquant-vslm-mcp"],
|
|
80
|
+
"env": { "ZQ_API_KEY": "<your api key>" }
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Restart Cursor.
|
|
87
|
+
|
|
88
|
+
### Zed
|
|
89
|
+
|
|
90
|
+
In `~/.config/zed/settings.json`:
|
|
91
|
+
|
|
92
|
+
```json
|
|
93
|
+
{
|
|
94
|
+
"context_servers": {
|
|
95
|
+
"zettaquant-vslm": {
|
|
96
|
+
"command": {
|
|
97
|
+
"path": "uvx",
|
|
98
|
+
"args": ["zettaquant-vslm-mcp"],
|
|
99
|
+
"env": { "ZQ_API_KEY": "<your api key>" }
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### Windsurf / other MCP hosts
|
|
107
|
+
|
|
108
|
+
Any host that supports the standard `mcpServers` config shape works — use the same `command` + `args` + `env` block as above.
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## Environment variables
|
|
113
|
+
|
|
114
|
+
| Variable | Required | Default | Notes |
|
|
115
|
+
|---|---|---|---|
|
|
116
|
+
| `ZQ_API_KEY` | ✅ | — | Your ZettaQuant API key. Must have the `vslm` scope. |
|
|
117
|
+
| `ZQ_BASE_URL` | | `https://api.zettaquant.ai` | Override for staging or a private gateway. |
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## Usage examples in the LLM
|
|
122
|
+
|
|
123
|
+
Once installed, just ask naturally. Some prompts that will trigger `vslm_predict`:
|
|
124
|
+
|
|
125
|
+
- *"Here are 40 sentences from Apple's Q3 earnings call. Pull out the ones about AI capex plans."*
|
|
126
|
+
- *"Filter these log lines down to anything related to lateral movement."*
|
|
127
|
+
- *"I pasted a 10-K risk section. Only show me sentences about supply-chain exposure."*
|
|
128
|
+
|
|
129
|
+
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.
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## What is MCP?
|
|
134
|
+
|
|
135
|
+
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**.
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## Development
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
uv venv
|
|
143
|
+
uv pip install -e ".[dev]"
|
|
144
|
+
export ZQ_API_KEY="..."
|
|
145
|
+
python -m zettaquant_vslm_mcp
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
The server speaks JSON-RPC on stdin/stdout. To poke it manually, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
npx @modelcontextprotocol/inspector uvx zettaquant-vslm-mcp
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## Troubleshooting
|
|
157
|
+
|
|
158
|
+
- **"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.
|
|
159
|
+
- **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`.
|
|
160
|
+
- **403 SCOPE_DENIED** → your key doesn't have the `vslm` scope. Contact ZettaQuant.
|
|
161
|
+
- **429 QUOTA_EXCEEDED** → you hit your per-period cap; the error message includes the reset time.
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
165
|
+
## License
|
|
166
|
+
|
|
167
|
+
MIT.
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# zettaquant-vslm-mcp
|
|
2
|
+
|
|
3
|
+
**MCP server that exposes ZettaQuant V-SLM to any MCP-aware LLM host.**
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## What it exposes
|
|
10
|
+
|
|
11
|
+
One tool, over stdio, via the [Model Context Protocol](https://modelcontextprotocol.io):
|
|
12
|
+
|
|
13
|
+
| Tool | Purpose |
|
|
14
|
+
|---|---|
|
|
15
|
+
| `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. |
|
|
16
|
+
|
|
17
|
+
The LLM decides when to call it on its own — no code you have to write in the host.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Install & configure
|
|
22
|
+
|
|
23
|
+
You need a ZettaQuant API key with the `vslm` scope. Get one at [zettaquant.ai](https://zettaquant.ai) (or ask your account contact).
|
|
24
|
+
|
|
25
|
+
### Claude Desktop
|
|
26
|
+
|
|
27
|
+
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
28
|
+
|
|
29
|
+
```json
|
|
30
|
+
{
|
|
31
|
+
"mcpServers": {
|
|
32
|
+
"zettaquant-vslm": {
|
|
33
|
+
"command": "uvx",
|
|
34
|
+
"args": ["zettaquant-vslm-mcp"],
|
|
35
|
+
"env": {
|
|
36
|
+
"ZQ_API_KEY": "<your api key>"
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Restart Claude Desktop. The tools appear under the "Tools" menu.
|
|
44
|
+
|
|
45
|
+
### Cursor
|
|
46
|
+
|
|
47
|
+
Edit `~/.cursor/mcp.json`:
|
|
48
|
+
|
|
49
|
+
```json
|
|
50
|
+
{
|
|
51
|
+
"mcpServers": {
|
|
52
|
+
"zettaquant-vslm": {
|
|
53
|
+
"command": "uvx",
|
|
54
|
+
"args": ["zettaquant-vslm-mcp"],
|
|
55
|
+
"env": { "ZQ_API_KEY": "<your api key>" }
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Restart Cursor.
|
|
62
|
+
|
|
63
|
+
### Zed
|
|
64
|
+
|
|
65
|
+
In `~/.config/zed/settings.json`:
|
|
66
|
+
|
|
67
|
+
```json
|
|
68
|
+
{
|
|
69
|
+
"context_servers": {
|
|
70
|
+
"zettaquant-vslm": {
|
|
71
|
+
"command": {
|
|
72
|
+
"path": "uvx",
|
|
73
|
+
"args": ["zettaquant-vslm-mcp"],
|
|
74
|
+
"env": { "ZQ_API_KEY": "<your api key>" }
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Windsurf / other MCP hosts
|
|
82
|
+
|
|
83
|
+
Any host that supports the standard `mcpServers` config shape works — use the same `command` + `args` + `env` block as above.
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## Environment variables
|
|
88
|
+
|
|
89
|
+
| Variable | Required | Default | Notes |
|
|
90
|
+
|---|---|---|---|
|
|
91
|
+
| `ZQ_API_KEY` | ✅ | — | Your ZettaQuant API key. Must have the `vslm` scope. |
|
|
92
|
+
| `ZQ_BASE_URL` | | `https://api.zettaquant.ai` | Override for staging or a private gateway. |
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Usage examples in the LLM
|
|
97
|
+
|
|
98
|
+
Once installed, just ask naturally. Some prompts that will trigger `vslm_predict`:
|
|
99
|
+
|
|
100
|
+
- *"Here are 40 sentences from Apple's Q3 earnings call. Pull out the ones about AI capex plans."*
|
|
101
|
+
- *"Filter these log lines down to anything related to lateral movement."*
|
|
102
|
+
- *"I pasted a 10-K risk section. Only show me sentences about supply-chain exposure."*
|
|
103
|
+
|
|
104
|
+
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.
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## What is MCP?
|
|
109
|
+
|
|
110
|
+
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**.
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Development
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
uv venv
|
|
118
|
+
uv pip install -e ".[dev]"
|
|
119
|
+
export ZQ_API_KEY="..."
|
|
120
|
+
python -m zettaquant_vslm_mcp
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The server speaks JSON-RPC on stdin/stdout. To poke it manually, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
npx @modelcontextprotocol/inspector uvx zettaquant-vslm-mcp
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## Troubleshooting
|
|
132
|
+
|
|
133
|
+
- **"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.
|
|
134
|
+
- **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`.
|
|
135
|
+
- **403 SCOPE_DENIED** → your key doesn't have the `vslm` scope. Contact ZettaQuant.
|
|
136
|
+
- **429 QUOTA_EXCEEDED** → you hit your per-period cap; the error message includes the reset time.
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## License
|
|
141
|
+
|
|
142
|
+
MIT.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "zettaquant-vslm-mcp"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "MCP server that exposes ZettaQuant V-SLM (topic-conditioned sentence relevancy) to any MCP-aware LLM host — Claude Desktop, Cursor, Zed, Windsurf."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.10"
|
|
7
|
+
license = { text = "MIT" }
|
|
8
|
+
authors = [
|
|
9
|
+
{ name = "ZettaQuant", email = "support@zettaquant.ai" }
|
|
10
|
+
]
|
|
11
|
+
keywords = ["mcp", "model-context-protocol", "vslm", "zettaquant", "llm", "tools", "claude", "cursor"]
|
|
12
|
+
classifiers = [
|
|
13
|
+
"Development Status :: 4 - Beta",
|
|
14
|
+
"Intended Audience :: Developers",
|
|
15
|
+
"License :: OSI Approved :: MIT License",
|
|
16
|
+
"Programming Language :: Python :: 3",
|
|
17
|
+
"Programming Language :: Python :: 3.10",
|
|
18
|
+
"Programming Language :: Python :: 3.11",
|
|
19
|
+
"Programming Language :: Python :: 3.12",
|
|
20
|
+
"Topic :: Software Development :: Libraries",
|
|
21
|
+
]
|
|
22
|
+
dependencies = [
|
|
23
|
+
"mcp>=1.2.0",
|
|
24
|
+
"httpx>=0.27.0",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
[project.scripts]
|
|
28
|
+
zettaquant-vslm-mcp = "zettaquant_vslm_mcp.server:main"
|
|
29
|
+
|
|
30
|
+
[project.urls]
|
|
31
|
+
Homepage = "https://zettaquant.ai"
|
|
32
|
+
Documentation = "https://github.com/zettaquant/zettaquant-vslm-mcp"
|
|
33
|
+
Source = "https://github.com/zettaquant/zettaquant-vslm-mcp"
|
|
34
|
+
Issues = "https://github.com/zettaquant/zettaquant-vslm-mcp/issues"
|
|
35
|
+
|
|
36
|
+
[build-system]
|
|
37
|
+
requires = ["hatchling"]
|
|
38
|
+
build-backend = "hatchling.build"
|
|
39
|
+
|
|
40
|
+
[tool.hatch.build.targets.wheel]
|
|
41
|
+
packages = ["src/zettaquant_vslm_mcp"]
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
"""
|
|
2
|
+
zettaquant-vslm-mcp — MCP server for ZettaQuant V-SLM.
|
|
3
|
+
|
|
4
|
+
Exposes one tool over stdio to any MCP-aware host (Claude Desktop, Cursor,
|
|
5
|
+
Zed, Windsurf, ChatGPT dev mode):
|
|
6
|
+
|
|
7
|
+
• vslm_predict Filter sentences to only those relevant to a topic.
|
|
8
|
+
Always uses the general_context_agent — broad-domain,
|
|
9
|
+
works across financial text, transcripts, news, reports,
|
|
10
|
+
and beyond.
|
|
11
|
+
|
|
12
|
+
Usage
|
|
13
|
+
-----
|
|
14
|
+
The host spawns this package as a subprocess (via `uvx zettaquant-vslm-mcp`
|
|
15
|
+
or `python -m zettaquant_vslm_mcp`) and speaks JSON-RPC over stdin/stdout.
|
|
16
|
+
Configure it in the host's MCP config with the user's ZettaQuant API key:
|
|
17
|
+
|
|
18
|
+
{
|
|
19
|
+
"mcpServers": {
|
|
20
|
+
"zettaquant-vslm": {
|
|
21
|
+
"command": "uvx",
|
|
22
|
+
"args": ["zettaquant-vslm-mcp"],
|
|
23
|
+
"env": { "ZQ_API_KEY": "<your api key>" }
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
from __future__ import annotations
|
|
30
|
+
|
|
31
|
+
import os
|
|
32
|
+
import sys
|
|
33
|
+
from typing import Any
|
|
34
|
+
|
|
35
|
+
import httpx
|
|
36
|
+
from mcp.server.fastmcp import FastMCP
|
|
37
|
+
|
|
38
|
+
# Base URL is overridable so we can point at staging / a private gateway.
|
|
39
|
+
ZQ_BASE_URL = os.environ.get("ZQ_BASE_URL", "https://api.zettaquant.ai").rstrip("/")
|
|
40
|
+
ZQ_API_KEY = os.environ.get("ZQ_API_KEY", "")
|
|
41
|
+
|
|
42
|
+
# The only agent this MCP server exposes. Broad-domain V-SLM head; works
|
|
43
|
+
# across financial text, transcripts, news, reports, logs. We intentionally
|
|
44
|
+
# do NOT expose the domain-specialised agents (transcript, log, legal, etc.)
|
|
45
|
+
# to keep the tool surface minimal for the LLM.
|
|
46
|
+
VSLM_AGENT = "general_context_agent"
|
|
47
|
+
|
|
48
|
+
# Bail loudly rather than fail mysteriously on first tool call. The host
|
|
49
|
+
# surfaces stderr in its logs, giving the user a clear "set ZQ_API_KEY"
|
|
50
|
+
# signal instead of an opaque "tool call returned 401".
|
|
51
|
+
if not ZQ_API_KEY:
|
|
52
|
+
print(
|
|
53
|
+
"zettaquant-vslm-mcp: ZQ_API_KEY environment variable is not set.\n"
|
|
54
|
+
" Set it in your MCP host config, e.g. Claude Desktop's\n"
|
|
55
|
+
" claude_desktop_config.json under mcpServers.<name>.env.ZQ_API_KEY.",
|
|
56
|
+
file=sys.stderr,
|
|
57
|
+
)
|
|
58
|
+
# Do NOT exit(1) — some hosts start the server before the first tool
|
|
59
|
+
# call and would treat an immediate exit as a crash loop. We surface
|
|
60
|
+
# the error per tool call instead (see _require_key below).
|
|
61
|
+
|
|
62
|
+
_HTTP_TIMEOUT_S = 120.0 # V-SLM predict can take a while on ~2K-sentence batches.
|
|
63
|
+
|
|
64
|
+
mcp = FastMCP("zettaquant-vslm")
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
# ---------------- helpers ----------------
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def _require_key() -> None:
|
|
71
|
+
"""Raise if ZQ_API_KEY is missing so the host surfaces a clear tool error."""
|
|
72
|
+
if not ZQ_API_KEY:
|
|
73
|
+
raise RuntimeError(
|
|
74
|
+
"ZQ_API_KEY is not set. Add it to the MCP host config under "
|
|
75
|
+
"mcpServers.<name>.env.ZQ_API_KEY, then restart the host."
|
|
76
|
+
)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def _headers() -> dict[str, str]:
|
|
80
|
+
return {"x-api-key": ZQ_API_KEY, "content-type": "application/json"}
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def _friendly_http_error(exc: httpx.HTTPStatusError) -> RuntimeError:
|
|
84
|
+
"""Turn common ZettaQuant HTTP errors into readable messages for the LLM."""
|
|
85
|
+
status = exc.response.status_code
|
|
86
|
+
try:
|
|
87
|
+
body = exc.response.json()
|
|
88
|
+
except Exception:
|
|
89
|
+
body = {"raw": exc.response.text[:500]}
|
|
90
|
+
|
|
91
|
+
if status == 401:
|
|
92
|
+
msg = "ZettaQuant auth failed (401). Check ZQ_API_KEY in your MCP host config."
|
|
93
|
+
elif status == 402:
|
|
94
|
+
msg = f"ZettaQuant plan not active (402). {body.get('message', '')}"
|
|
95
|
+
elif status == 403:
|
|
96
|
+
msg = f"ZettaQuant access denied (403). {body.get('message', body)}"
|
|
97
|
+
elif status == 429:
|
|
98
|
+
msg = (
|
|
99
|
+
f"ZettaQuant quota exceeded (429). "
|
|
100
|
+
f"{body.get('message', '')} — quota resets at {body.get('resets_at', 'next period')}."
|
|
101
|
+
)
|
|
102
|
+
elif status in (502, 503):
|
|
103
|
+
msg = f"ZettaQuant upstream temporarily unavailable ({status}); retry later."
|
|
104
|
+
else:
|
|
105
|
+
msg = f"ZettaQuant returned HTTP {status}: {body}"
|
|
106
|
+
return RuntimeError(msg)
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
# ---------------- tools ----------------
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
@mcp.tool()
|
|
113
|
+
async def vslm_predict(
|
|
114
|
+
sentences: list[str],
|
|
115
|
+
query: str,
|
|
116
|
+
) -> dict[str, Any]:
|
|
117
|
+
"""Filter a list of sentences to only those relevant to `query`.
|
|
118
|
+
|
|
119
|
+
Use this BEFORE feeding noisy context (earnings-call transcripts, news
|
|
120
|
+
articles, long reports, log lines) to an LLM — it typically cuts token
|
|
121
|
+
count 5-10x without losing signal. Chain it with your own model, or with
|
|
122
|
+
a ZettaQuant classifier.
|
|
123
|
+
|
|
124
|
+
Args:
|
|
125
|
+
sentences: raw input sentences; ~2000 per call is comfortable.
|
|
126
|
+
query: natural-language description of the topic to filter for
|
|
127
|
+
(e.g. "AI capex plans", "rate cuts", "supply chain risk").
|
|
128
|
+
|
|
129
|
+
Returns:
|
|
130
|
+
dict with:
|
|
131
|
+
relevant_sentences: sentences that passed the filter, original order.
|
|
132
|
+
total_sentences, relevant_count: counts to compute savings.
|
|
133
|
+
topic_used: the topic string the model actually filtered against.
|
|
134
|
+
topic_source: "zettaquant" (server-derived) or "caller" (you supplied).
|
|
135
|
+
model_id: which V-SLM head handled the request.
|
|
136
|
+
"""
|
|
137
|
+
_require_key()
|
|
138
|
+
if not sentences:
|
|
139
|
+
return {
|
|
140
|
+
"agent": VSLM_AGENT,
|
|
141
|
+
"model_id": None,
|
|
142
|
+
"topic_used": query,
|
|
143
|
+
"topic_source": "caller",
|
|
144
|
+
"relevant_sentences": [],
|
|
145
|
+
"total_sentences": 0,
|
|
146
|
+
"relevant_count": 0,
|
|
147
|
+
}
|
|
148
|
+
payload = {"agent": VSLM_AGENT, "sentences": sentences, "query": query}
|
|
149
|
+
async with httpx.AsyncClient(timeout=_HTTP_TIMEOUT_S) as client:
|
|
150
|
+
try:
|
|
151
|
+
r = await client.post(
|
|
152
|
+
f"{ZQ_BASE_URL}/v1/vslm/predict",
|
|
153
|
+
headers=_headers(),
|
|
154
|
+
json=payload,
|
|
155
|
+
)
|
|
156
|
+
r.raise_for_status()
|
|
157
|
+
except httpx.HTTPStatusError as e:
|
|
158
|
+
raise _friendly_http_error(e) from None
|
|
159
|
+
return r.json()
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
# ---------------- entrypoint ----------------
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def main() -> None:
|
|
166
|
+
"""Console-script entrypoint. Runs stdio transport (default for FastMCP)."""
|
|
167
|
+
mcp.run()
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
if __name__ == "__main__":
|
|
171
|
+
main()
|