quantgist-mcp 0.1.0__tar.gz

quantgist_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  package-check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - uses: astral-sh/setup-uv@v5
+
+      - run: uv sync
+      - run: uv run python -c "import quantgist_mcp"
+      - run: uv build
+
+  publish:
+    # Publishes to PyPI via the trusted publisher bound to this workflow
+    # (QuantGist-Technologies/QuantGist_MCP · ci.yml). Runs only on v* tags.
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: package-check
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

quantgist_mcp-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+CLAUDE.md
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+uv.lock
+.env
+.env.local
+.DS_Store
+Thumbs.db

quantgist_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0 - 2026-05-25
+
+- Prepared the MCP server for public launch with repository metadata and CI.
+- Exposes QuantGist macro event tools for agent workflows.

quantgist_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuantGist
+
+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.

quantgist_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: quantgist-mcp
+Version: 0.1.0
+Summary: MCP server — exposes QuantGist macro event tools to Claude and AI agents
+Author-email: QuantGist <dev@quantgist.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.0.0
+Description-Content-Type: text/markdown
+
+# QuantGist MCP Server
+
+Exposes [QuantGist](https://quantgist.com) macro-economic event data as **Model Context Protocol (MCP)** tools so Claude and other AI agents can query calendars, check event proximity, and assess trade safety — all within a conversation.
+
+## What it does
+
+The server registers eleven tools that any MCP-compatible client (Claude Desktop, Claude Code, custom agents) can call:
+
+**Macro economic events**
+
+| Tool | Description |
+|------|-------------|
+| `get_upcoming_events` | Events scheduled in the next N hours, filtered by impact |
+| `get_events_range` | Events in a date range with optional country/symbol/impact filters |
+| `check_safe_to_trade` | Is it safe to trade a symbol right now? (high-impact event proximity check) |
+| `get_economic_calendar` | Full day calendar grouped by time, formatted as a schedule |
+| `get_event_detail` | Full details for one event by ID (actual, forecast, previous, symbols) |
+
+**Earnings**
+
+| Tool | Description |
+|------|-------------|
+| `get_earnings_upcoming` | Next upcoming earnings reports across all tickers, with EPS/revenue estimates |
+| `get_earnings_for_ticker` | Earnings history for one ticker (estimate vs actual, beat/miss, EDGAR links) |
+| `get_earnings_summary` | Beat / miss / in-line counts and overall beat rate for a ticker |
+| `get_earnings_surprises` | Largest EPS surprises across the market in the latest reports |
+| `get_earnings_season_summary` | Index-level summary of the current earnings season |
+
+**Markets**
+
+| Tool | Description |
+|------|-------------|
+| `get_markets_overview` | End-of-day quotes for major indices and instruments (S&P 500, Nasdaq, gold, oil…) |
+
+## Requirements
+
+- Python 3.10+
+- A QuantGist API key — get one at [quantgist.com](https://quantgist.com) (free tier: 100 calls/day)
+
+## Installation
+
+### Option A — install from the package (recommended)
+
+```bash
+pip install quantgist-mcp
+# or with uv:
+uv pip install quantgist-mcp
+```
+
+### Option B — install from source (development)
+
+```bash
+git clone https://github.com/QuantGist-Technologies/QuantGist_MCP
+cd QuantGist_MCP
+uv sync          # installs all dependencies into a venv
+uv run quantgist-mcp   # start the server
+```
+
+## Claude Desktop configuration
+
+Locate your Claude Desktop config file:
+
+| Platform | Path |
+|----------|------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+
+Add the `quantgist` server block (see `claude_desktop_config_example.json`):
+
+```json
+{
+  "mcpServers": {
+    "quantgist": {
+      "command": "quantgist-mcp",
+      "env": {
+        "QUANTGIST_API_KEY": "qg_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving. The tools will appear in the tool list.
+
+### Using `uv run` instead of a global install
+
+If you prefer not to install globally, point Claude Desktop at `uv run`:
+
+```json
+{
+  "mcpServers": {
+    "quantgist": {
+      "command": "uv",
+      "args": ["run", "--directory", "/absolute/path/to/Quangist_MCP", "quantgist-mcp"],
+      "env": {
+        "QUANTGIST_API_KEY": "qg_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+## Claude Code configuration
+
+Add to `.claude/mcp_settings.json` in your project (or the global `~/.claude/mcp_settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "quantgist": {
+      "command": "quantgist-mcp",
+      "env": {
+        "QUANTGIST_API_KEY": "qg_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+## Tool reference
+
+### `get_upcoming_events`
+
+Returns events in the next N hours.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `hours` | integer (1–168) | 24 | Look-ahead window in hours |
+| `impact` | high \| medium \| low \| all | high | Impact filter |
+
+### `get_events_range`
+
+Returns events in a date range.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `from_date` | ISO string | Yes | Start date/datetime |
+| `to_date` | ISO string | Yes | End date/datetime |
+| `country` | string | No | 2-letter country code (e.g. "US") |
+| `impact` | enum | No | high \| medium \| low \| all |
+| `symbol` | string | No | Trading symbol (e.g. "XAUUSD") |
+
+### `check_safe_to_trade`
+
+Checks if a symbol is safe to trade based on nearby high-impact events.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `symbol` | string | required | Symbol to check (e.g. "XAUUSD") |
+| `minutes_before` | integer (0–120) | 10 | Flag unsafe N minutes before an event |
+| `minutes_after` | integer (0–120) | 5 | Flag unsafe N minutes after an event |
+
+Returns a JSON object:
+```json
+{
+  "symbol": "XAUUSD",
+  "safe": false,
+  "reason": "High-impact event within window: US CPI (YoY). Avoid trading XAUUSD until the window passes.",
+  "dangerous_events_count": 1,
+  "next_event": {
+    "id": "abc123",
+    "title": "US CPI (YoY)",
+    "currency": "USD",
+    "impact": "high",
+    "release_time_utc": "2025-01-15T13:30:00Z",
+    "minutes_from_now": 7.3
+  },
+  "window": { "minutes_before": 10, "minutes_after": 5 },
+  "checked_at_utc": "2025-01-15 13:22 UTC"
+}
+```
+
+### `get_economic_calendar`
+
+Returns the day's calendar grouped by release time.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `date` | ISO date | today (UTC) | Date to fetch |
+| `impact` | enum | high | Impact filter |
+
+### `get_event_detail`
+
+Returns full detail for one event.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `event_id` | string | Yes | Event ID from any other tool |
+
+### `get_earnings_upcoming`
+
+Returns the next upcoming earnings reports across all tickers, ordered by report date.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `limit` | integer (1–100) | 20 | Number of upcoming reports to return |
+
+### `get_earnings_for_ticker`
+
+Returns earnings history for a single ticker (EPS estimate vs actual, revenue, beat/miss, EDGAR links).
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `ticker` | string | required | Stock ticker, e.g. "AAPL" |
+| `limit` | integer (1–50) | 10 | Number of historical reports to return |
+
+### `get_earnings_summary`
+
+Returns beat / miss / in-line counts and overall beat rate for a ticker.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `ticker` | string | Yes | Stock ticker, e.g. "AAPL" |
+
+### `get_earnings_surprises`
+
+Returns the largest EPS surprises across the market in the most recent reports.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `limit` | integer (1–50) | 20 | Number of top surprises to return |
+
+### `get_earnings_season_summary`
+
+Returns the index-level summary of the current earnings season (total reports, overall beat rate, average EPS surprise, season label). No parameters.
+
+### `get_markets_overview`
+
+Returns end-of-day quotes for major market indices and instruments (S&P 500, Nasdaq, Dow Jones, gold, oil, etc.). No parameters.
+
+## Example prompts
+
+These prompts work out of the box once the server is connected:
+
+- "What high-impact events are in the next 4 hours?"
+- "Is it safe to trade XAUUSD right now?"
+- "Show me today's full economic calendar"
+- "Show me this week's high-impact USD events"
+- "What macro events affect EURUSD this Friday?"
+- "Get me details on event ID abc123"
+- "Check if GBPUSD is safe to trade with a 15-minute buffer before events"
+- "Which companies report earnings soon?"
+- "Show me AAPL's earnings beat rate"
+- "What were the biggest EPS surprises this season?"
+- "Give me a quick market overview"
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `QUANTGIST_API_KEY` | Yes | Your QuantGist API key (`qg_live_...` or `qg_test_...`) |
+
+## Development
+
+```bash
+uv sync
+uv run quantgist-mcp          # run the MCP server
+uv run pytest                 # run tests (if present)
+uv run ruff check src/        # lint
+uv run ruff format src/       # format
+```
+
+## API rate limits
+
+The free tier allows 100 API calls/day with up to 365 days of event history. Each tool invocation makes 1–2 API calls. Upgrade at [quantgist.com/pricing](https://quantgist.com/pricing) for higher limits.
+
+## License
+
+MIT

quantgist_mcp-0.1.0/README.md

@@ -0,0 +1,270 @@
+# QuantGist MCP Server
+
+Exposes [QuantGist](https://quantgist.com) macro-economic event data as **Model Context Protocol (MCP)** tools so Claude and other AI agents can query calendars, check event proximity, and assess trade safety — all within a conversation.
+
+## What it does
+
+The server registers eleven tools that any MCP-compatible client (Claude Desktop, Claude Code, custom agents) can call:
+
+**Macro economic events**
+
+| Tool | Description |
+|------|-------------|
+| `get_upcoming_events` | Events scheduled in the next N hours, filtered by impact |
+| `get_events_range` | Events in a date range with optional country/symbol/impact filters |
+| `check_safe_to_trade` | Is it safe to trade a symbol right now? (high-impact event proximity check) |
+| `get_economic_calendar` | Full day calendar grouped by time, formatted as a schedule |
+| `get_event_detail` | Full details for one event by ID (actual, forecast, previous, symbols) |
+
+**Earnings**
+
+| Tool | Description |
+|------|-------------|
+| `get_earnings_upcoming` | Next upcoming earnings reports across all tickers, with EPS/revenue estimates |
+| `get_earnings_for_ticker` | Earnings history for one ticker (estimate vs actual, beat/miss, EDGAR links) |
+| `get_earnings_summary` | Beat / miss / in-line counts and overall beat rate for a ticker |
+| `get_earnings_surprises` | Largest EPS surprises across the market in the latest reports |
+| `get_earnings_season_summary` | Index-level summary of the current earnings season |
+
+**Markets**
+
+| Tool | Description |
+|------|-------------|
+| `get_markets_overview` | End-of-day quotes for major indices and instruments (S&P 500, Nasdaq, gold, oil…) |
+
+## Requirements
+
+- Python 3.10+
+- A QuantGist API key — get one at [quantgist.com](https://quantgist.com) (free tier: 100 calls/day)
+
+## Installation
+
+### Option A — install from the package (recommended)
+
+```bash
+pip install quantgist-mcp
+# or with uv:
+uv pip install quantgist-mcp
+```
+
+### Option B — install from source (development)
+
+```bash
+git clone https://github.com/QuantGist-Technologies/QuantGist_MCP
+cd QuantGist_MCP
+uv sync          # installs all dependencies into a venv
+uv run quantgist-mcp   # start the server
+```
+
+## Claude Desktop configuration
+
+Locate your Claude Desktop config file:
+
+| Platform | Path |
+|----------|------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+
+Add the `quantgist` server block (see `claude_desktop_config_example.json`):
+
+```json
+{
+  "mcpServers": {
+    "quantgist": {
+      "command": "quantgist-mcp",
+      "env": {
+        "QUANTGIST_API_KEY": "qg_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving. The tools will appear in the tool list.
+
+### Using `uv run` instead of a global install
+
+If you prefer not to install globally, point Claude Desktop at `uv run`:
+
+```json
+{
+  "mcpServers": {
+    "quantgist": {
+      "command": "uv",
+      "args": ["run", "--directory", "/absolute/path/to/Quangist_MCP", "quantgist-mcp"],
+      "env": {
+        "QUANTGIST_API_KEY": "qg_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+## Claude Code configuration
+
+Add to `.claude/mcp_settings.json` in your project (or the global `~/.claude/mcp_settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "quantgist": {
+      "command": "quantgist-mcp",
+      "env": {
+        "QUANTGIST_API_KEY": "qg_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+## Tool reference
+
+### `get_upcoming_events`
+
+Returns events in the next N hours.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `hours` | integer (1–168) | 24 | Look-ahead window in hours |
+| `impact` | high \| medium \| low \| all | high | Impact filter |
+
+### `get_events_range`
+
+Returns events in a date range.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `from_date` | ISO string | Yes | Start date/datetime |
+| `to_date` | ISO string | Yes | End date/datetime |
+| `country` | string | No | 2-letter country code (e.g. "US") |
+| `impact` | enum | No | high \| medium \| low \| all |
+| `symbol` | string | No | Trading symbol (e.g. "XAUUSD") |
+
+### `check_safe_to_trade`
+
+Checks if a symbol is safe to trade based on nearby high-impact events.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `symbol` | string | required | Symbol to check (e.g. "XAUUSD") |
+| `minutes_before` | integer (0–120) | 10 | Flag unsafe N minutes before an event |
+| `minutes_after` | integer (0–120) | 5 | Flag unsafe N minutes after an event |
+
+Returns a JSON object:
+```json
+{
+  "symbol": "XAUUSD",
+  "safe": false,
+  "reason": "High-impact event within window: US CPI (YoY). Avoid trading XAUUSD until the window passes.",
+  "dangerous_events_count": 1,
+  "next_event": {
+    "id": "abc123",
+    "title": "US CPI (YoY)",
+    "currency": "USD",
+    "impact": "high",
+    "release_time_utc": "2025-01-15T13:30:00Z",
+    "minutes_from_now": 7.3
+  },
+  "window": { "minutes_before": 10, "minutes_after": 5 },
+  "checked_at_utc": "2025-01-15 13:22 UTC"
+}
+```
+
+### `get_economic_calendar`
+
+Returns the day's calendar grouped by release time.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `date` | ISO date | today (UTC) | Date to fetch |
+| `impact` | enum | high | Impact filter |
+
+### `get_event_detail`
+
+Returns full detail for one event.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `event_id` | string | Yes | Event ID from any other tool |
+
+### `get_earnings_upcoming`
+
+Returns the next upcoming earnings reports across all tickers, ordered by report date.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `limit` | integer (1–100) | 20 | Number of upcoming reports to return |
+
+### `get_earnings_for_ticker`
+
+Returns earnings history for a single ticker (EPS estimate vs actual, revenue, beat/miss, EDGAR links).
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `ticker` | string | required | Stock ticker, e.g. "AAPL" |
+| `limit` | integer (1–50) | 10 | Number of historical reports to return |
+
+### `get_earnings_summary`
+
+Returns beat / miss / in-line counts and overall beat rate for a ticker.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `ticker` | string | Yes | Stock ticker, e.g. "AAPL" |
+
+### `get_earnings_surprises`
+
+Returns the largest EPS surprises across the market in the most recent reports.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `limit` | integer (1–50) | 20 | Number of top surprises to return |
+
+### `get_earnings_season_summary`
+
+Returns the index-level summary of the current earnings season (total reports, overall beat rate, average EPS surprise, season label). No parameters.
+
+### `get_markets_overview`
+
+Returns end-of-day quotes for major market indices and instruments (S&P 500, Nasdaq, Dow Jones, gold, oil, etc.). No parameters.
+
+## Example prompts
+
+These prompts work out of the box once the server is connected:
+
+- "What high-impact events are in the next 4 hours?"
+- "Is it safe to trade XAUUSD right now?"
+- "Show me today's full economic calendar"
+- "Show me this week's high-impact USD events"
+- "What macro events affect EURUSD this Friday?"
+- "Get me details on event ID abc123"
+- "Check if GBPUSD is safe to trade with a 15-minute buffer before events"
+- "Which companies report earnings soon?"
+- "Show me AAPL's earnings beat rate"
+- "What were the biggest EPS surprises this season?"
+- "Give me a quick market overview"
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `QUANTGIST_API_KEY` | Yes | Your QuantGist API key (`qg_live_...` or `qg_test_...`) |
+
+## Development
+
+```bash
+uv sync
+uv run quantgist-mcp          # run the MCP server
+uv run pytest                 # run tests (if present)
+uv run ruff check src/        # lint
+uv run ruff format src/       # format
+```
+
+## API rate limits
+
+The free tier allows 100 API calls/day with up to 365 days of event history. Each tool invocation makes 1–2 API calls. Upgrade at [quantgist.com/pricing](https://quantgist.com/pricing) for higher limits.
+
+## License
+
+MIT

quantgist_mcp-0.1.0/claude_desktop_config_example.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "quantgist": {
+      "command": "quantgist-mcp",
+      "env": {
+        "QUANTGIST_API_KEY": "qg_live_REPLACE_WITH_YOUR_KEY"
+      }
+    }
+  }
+}

quantgist_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "quantgist-mcp"
+version = "0.1.0"
+description = "MCP server — exposes QuantGist macro event tools to Claude and AI agents"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "QuantGist", email = "dev@quantgist.com" }]
+requires-python = ">=3.10"
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.scripts]
+quantgist-mcp = "quantgist_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/quantgist_mcp"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"

quantgist_mcp-0.1.0/src/quantgist_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""QuantGist MCP server package."""
+
+__version__ = "0.1.0"