vanoe-intelligence-mcp 0.1.0__py3-none-any.whl

mcp_server/__main__.py

@@ -0,0 +1,4 @@
+from mcp_server.server import main
+
+if __name__ == "__main__":
+    main()

mcp_server/client.py

@@ -0,0 +1,72 @@
+"""Thin HTTP client for the Vanoe Market Intelligence API — one function per
+/v1 GET endpoint.
+
+Auth: Authorization: Bearer <VANOE_API_KEY>. Base URL: VANOE_API_BASE_URL
+(defaults to https://api.vanoe.ai; point it at a local instance for dev).
+The older INTEL_API_KEY / INTEL_API_BASE_URL names are still honoured.
+
+On any non-2xx response, raises IntelAPIError carrying the API's own
+structured {"error": {code, message, request_id}} body when present, so a
+tool caller sees the SAME message a developer would get calling the API
+directly (e.g. "Monthly quota exceeded..."), not a raw HTTP status.
+"""
+from __future__ import annotations
+
+import os
+
+import httpx
+
+DEFAULT_BASE_URL = "https://api.vanoe.ai"
+SIGNUP_URL = "https://api.vanoe.ai/signup"
+_TIMEOUT_SECONDS = 20
+
+
+class IntelAPIError(Exception):
+    def __init__(self, status_code: int, code: str, message: str):
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        super().__init__(f"{message} (code={code}, http_status={status_code})")
+
+
+class MissingApiKeyError(Exception):
+    def __init__(self):
+        super().__init__(
+            f"VANOE_API_KEY is not set. Get a free key at {SIGNUP_URL} and set the "
+            "VANOE_API_KEY environment variable before starting this MCP server."
+        )
+
+
+def _env(new: str, old: str) -> str | None:
+    return os.environ.get(new) or os.environ.get(old)
+
+
+def _base_url() -> str:
+    return (_env("VANOE_API_BASE_URL", "INTEL_API_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+
+def _headers() -> dict:
+    key = _env("VANOE_API_KEY", "INTEL_API_KEY")
+    if not key:
+        raise MissingApiKeyError()
+    return {"Authorization": f"Bearer {key}"}
+
+
+async def get(path: str, params: dict | None = None) -> dict:
+    url = f"{_base_url()}{path}"
+    async with httpx.AsyncClient(timeout=_TIMEOUT_SECONDS) as http:
+        try:
+            r = await http.get(url, params=params, headers=_headers())
+        except httpx.RequestError as e:
+            raise IntelAPIError(0, "connection_error",
+                                f"Could not reach the API at {_base_url()}: {e}") from e
+
+    if r.status_code >= 400:
+        try:
+            body = r.json()
+            err = body.get("error", {})
+            raise IntelAPIError(r.status_code, err.get("code", "unknown_error"),
+                                err.get("message", r.text))
+        except ValueError:
+            raise IntelAPIError(r.status_code, "unknown_error", r.text)
+    return r.json()

mcp_server/server.py

@@ -0,0 +1,129 @@
+"""Vanoe Market Intelligence MCP server — exposes the API's signals as MCP
+tools so any MCP-capable AI assistant (Claude Desktop, Claude Code, etc.) can
+call them directly.
+
+This is a thin authenticated client, not a free bypass: every tool call
+makes a real, metered call against your plan using your own VANOE_API_KEY,
+exactly like calling the REST API yourself.
+
+Setup:
+  VANOE_API_KEY       your sk_live_... key (required) — free at https://api.vanoe.ai/signup
+  VANOE_API_BASE_URL  defaults to https://api.vanoe.ai; point at a local
+                      instance for development
+
+Run: vanoe-intelligence-mcp   (or: python -m mcp_server) — stdio transport,
+for Claude Desktop / Claude Code style MCP client configs.
+
+Tools never raise — every failure (missing key, network error, an API
+4xx/5xx) is caught and returned as a {"error": {...}} JSON payload in the
+tool result, not an exception. This is deliberate: a raised exception from a
+tool crashes with UnexpectedToolError rather than being cleanly surfaced to
+the caller (confirmed against the installed SDK version), so tools return a
+predictable JSON shape either way instead of depending on that behavior.
+"""
+from __future__ import annotations
+
+import json
+
+from mcp.server.mcpserver import MCPServer
+
+from mcp_server import client
+
+mcp = MCPServer(
+    name="vanoe-market-intelligence",
+    version="0.1.0",
+    instructions=(
+        "Vanoe Market Intelligence signals: four-stage trend analysis, Point & "
+        "Figure patterns, sector breadth, a composite verdict score, macro "
+        "regime, insider filings, and the economic calendar. All output is "
+        "informational data only — not financial advice, and not a "
+        "recommendation, solicitation, or offer to buy or sell any security."
+    ),
+)
+
+
+async def _call(path: str, params: dict | None = None) -> str:
+    """GET the API and return the JSON result as a string, or a
+    {"error": {...}} JSON string on any failure — tools never raise."""
+    try:
+        data = await client.get(path, params)
+        return json.dumps(data, indent=2)
+    except client.MissingApiKeyError as e:
+        return json.dumps({"error": {"code": "missing_api_key", "message": str(e)}}, indent=2)
+    except client.IntelAPIError as e:
+        return json.dumps(
+            {"error": {"code": e.code, "message": e.message, "http_status": e.status_code}},
+            indent=2,
+        )
+    except Exception as e:  # last-resort guard — tools must never raise
+        return json.dumps({"error": {"code": "mcp_server_error", "message": str(e)}}, indent=2)
+
+
+@mcp.tool(description="Macro regime (risk_on/neutral/risk_off), rates, inflation, yield curve, positioning.")
+async def get_macro() -> str:
+    return await _call("/v1/macro")
+
+
+@mcp.tool(description=(
+    "Stage analysis (1=Basing, 2=Advancing, 3=Topping, 4=Declining) "
+    "for up to 50 tickers. Pass tickers as a comma-separated string, e.g. "
+    "'AAPL,MSFT,NVDA'."
+))
+async def get_stage(tickers: str) -> str:
+    return await _call("/v1/signals/stage", {"tickers": tickers})
+
+
+@mcp.tool(description=(
+    "Historical weekly trend-stage series for one ticker, walk-forward "
+    "computed (no lookahead) — the only commercial source of trend "
+    "stages as a backtest-safe data series. weeks defaults to 104, max 520."
+))
+async def get_stage_history(ticker: str, weeks: int = 104) -> str:
+    return await _call("/v1/signals/stage/history", {"ticker": ticker, "weeks": weeks})
+
+
+@mcp.tool(description=(
+    "Point & Figure signal, breakout pattern, and relative strength vs SPY, "
+    "for up to 50 tickers. Pass tickers as a comma-separated string."
+))
+async def get_pnf(tickers: str) -> str:
+    return await _call("/v1/signals/pnf", {"tickers": tickers})
+
+
+@mcp.tool(description="Bullish-percent breadth by sector — the % of names in each sector on a Point & Figure buy signal.")
+async def get_sector_breadth() -> str:
+    return await _call("/v1/sector-breadth")
+
+
+@mcp.tool(description=(
+    "Composite verdict for one ticker: fuses trend stage, Point & "
+    "Figure, insider-transaction clusters, and macro regime into a 0-100 "
+    "score, an accumulate/hold/distribute/avoid enum, and a plain-English "
+    "rationale. One call replaces separately calling stage, pnf, filings, "
+    "and macro."
+))
+async def get_verdict(ticker: str) -> str:
+    return await _call(f"/v1/verdict/{ticker}")
+
+
+@mcp.tool(description="Recent SEC insider transactions (Form 4) and 8-K filings for one ticker.")
+async def get_filings(ticker: str) -> str:
+    return await _call(f"/v1/filings/{ticker}")
+
+
+@mcp.tool(description="Upcoming macro events (FOMC, CPI, payrolls) within a look-ahead window in days (default 10, max 60).")
+async def get_calendar(within_days: int = 10) -> str:
+    return await _call("/v1/calendar", {"within_days": within_days})
+
+
+@mcp.tool(description="Your current billing-period usage and remaining credit quota on your plan. Free — never counts against quota.")
+async def get_usage() -> str:
+    return await _call("/v1/usage")
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

vanoe_intelligence_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: vanoe-intelligence-mcp
+Version: 0.1.0
+Summary: MCP server for the Vanoe Market Intelligence API: composite verdicts, trend-stage analysis, Point & Figure, sector breadth, macro regime and SEC filings as tools for Claude and other MCP clients.
+Author-email: VanoeAI Ltd <support@vanoe.ai>
+License: MIT
+Project-URL: Homepage, https://api.vanoe.ai
+Project-URL: Documentation, https://api.vanoe.ai/docs
+Project-URL: Get an API key, https://api.vanoe.ai/signup
+Keywords: mcp,model-context-protocol,finance,stocks,trading,signals,claude
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<3.0,>=2.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Dynamic: license-file
+
+# Vanoe Market Intelligence MCP server
+
+Exposes the [Vanoe Market Intelligence API](https://api.vanoe.ai) as tools any
+MCP-capable AI assistant (Claude Desktop, Claude Code, Cursor, etc.) can call
+directly: a composite 0–100 verdict per ticker, trend-stage analysis (current
+and a backtest-safe weekly history), Point & Figure signals, sector breadth,
+the macro risk regime, SEC insider and 8-K filings, the macro calendar, and
+your usage.
+
+This is a thin authenticated client, not a free tier: every tool call is a
+real, metered call against your plan using your own API key, exactly like
+calling the REST API yourself. Get a free key (1,000 credits a month, no card)
+at https://api.vanoe.ai/signup.
+
+> Informational data only. Not financial advice. See https://api.vanoe.ai/terms.
+
+## Install
+
+No install step is needed with [uv](https://docs.astral.sh/uv/) — `uvx` fetches
+and runs the package on demand:
+
+```
+uvx vanoe-intelligence-mcp
+```
+
+Or install it permanently with `pipx install vanoe-intelligence-mcp` or
+`pip install vanoe-intelligence-mcp`, which puts a `vanoe-intelligence-mcp`
+command on your PATH.
+
+## Configure your MCP client
+
+Set one environment variable, `VANOE_API_KEY`. `VANOE_API_BASE_URL` is optional
+and defaults to `https://api.vanoe.ai`.
+
+**Claude Desktop** (`claude_desktop_config.json`) and most other clients:
+
+```json
+{
+  "mcpServers": {
+    "vanoe": {
+      "command": "uvx",
+      "args": ["vanoe-intelligence-mcp"],
+      "env": { "VANOE_API_KEY": "sk_live_your_key_here" }
+    }
+  }
+}
+```
+
+**Claude Code**:
+
+```
+claude mcp add vanoe -e VANOE_API_KEY=sk_live_your_key_here -- uvx vanoe-intelligence-mcp
+```
+
+Then ask your assistant things like *"What's the verdict on NVDA and why?"*,
+*"Which stage are AAPL, MSFT and AMD in?"*, or *"Is the macro regime risk-on
+right now?"* — it will call the tools below.
+
+## Tools
+
+| Tool | API call | Credits |
+|---|---|---|
+| `get_verdict(ticker)` | `GET /v1/verdict/{ticker}` | 5 |
+| `get_stage(tickers)` | `GET /v1/signals/stage` | 1 per ticker |
+| `get_stage_history(ticker, weeks)` | `GET /v1/signals/stage/history` | 5 |
+| `get_pnf(tickers)` | `GET /v1/signals/pnf` | 1 per ticker |
+| `get_sector_breadth()` | `GET /v1/sector-breadth` | 1 |
+| `get_macro()` | `GET /v1/macro` | 1 |
+| `get_filings(ticker)` | `GET /v1/filings/{ticker}` | 1 |
+| `get_calendar()` | `GET /v1/calendar` | 1 |
+| `get_usage()` | `GET /v1/usage` | 0 |
+
+Tools never raise. Any failure — missing key, network error, quota exceeded,
+an unknown ticker — comes back as `{"error": {"code", "message",
+"http_status"}}` carrying the API's own message, so the assistant can explain
+what happened instead of crashing the call.
+
+Webhook management is deliberately not exposed: it is account administration,
+not something to do mid-conversation. Use the REST API for that.
+
+## Development
+
+```
+cd mcp_server
+python -m venv .venv && . .venv/bin/activate     # Windows: .venv\Scripts\activate
+pip install -e '.[test]'
+pytest tests
+VANOE_API_BASE_URL=http://localhost:8000 VANOE_API_KEY=sk_live_… vanoe-intelligence-mcp
+```
+
+Install it in its own virtualenv, separate from the API server's own
+`requirements.txt`: the `mcp` SDK pulls in a newer `starlette` than the API's
+FastAPI pin tolerates, and sharing one environment breaks the API server with
+`Router.__init__() got an unexpected keyword argument 'on_startup'`. End users
+never hit this (the MCP server runs on their machine, next to their assistant).
+
+`tests/manual_e2e_smoke.py` runs the real server as a subprocess over stdio
+against a reachable API with a real key; it is not part of `pytest`.
+
+The MCP Python SDK is on v2: the server class is
+`mcp.server.mcpserver.MCPServer` (older tutorials show `FastMCP` at a
+different import path).
+
+## Releasing
+
+```
+cd mcp_server
+python -m build
+twine upload dist/*
+```
+
+Bump `version` in `pyproject.toml` first. The older `INTEL_API_KEY` /
+`INTEL_API_BASE_URL` variable names are still accepted for compatibility.

vanoe_intelligence_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+mcp_server/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_server/__main__.py,sha256=N_V5rRv2sQid3ZFBCCg4gQWGqkx1Q0ngJD-AOILW2MY,74
+mcp_server/client.py,sha256=DlxLYY2SNanT98KvoY3nXdZU3fR7dYB49fl6NouCFV8,2511
+mcp_server/server.py,sha256=IPIMhjIxcdZ_tuuQ7-0URmT_EABQt7g8sE2KBCnT8lk,5128
+vanoe_intelligence_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=KXcMg0Wuenl580V7_EaZN63N1Uerdg4cSsz6qJOvkn0,1068
+vanoe_intelligence_mcp-0.1.0.dist-info/METADATA,sha256=m5qjGSJnT9zIDBmx8ENGPAqT9biH5iBGwb_4htXnlCQ,5328
+vanoe_intelligence_mcp-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+vanoe_intelligence_mcp-0.1.0.dist-info/entry_points.txt,sha256=4Ys3dMpnOERNXK4DaDUMubQnOZYGSKqUYYaGF268-TA,66
+vanoe_intelligence_mcp-0.1.0.dist-info/top_level.txt,sha256=R49ZBwHkJvJ-AJ8o9wy6MuCs0rvZpyCEuvdwhI4PpHs,11
+vanoe_intelligence_mcp-0.1.0.dist-info/RECORD,,

vanoe_intelligence_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vanoe_intelligence_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vanoe-intelligence-mcp = mcp_server.server:main

vanoe_intelligence_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VanoeAI Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vanoe_intelligence_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcp_server