hodlodds-mcp 0.1.0__tar.gz

hodlodds_mcp-0.1.0/LICENSE

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

hodlodds_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: hodlodds-mcp
+Version: 0.1.0
+Summary: Local stdio MCP tools for HodlOdds crash odds with bounded USDC payments
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hodlodds<0.4,>=0.3.0
+Requires-Dist: mcp<3,>=2.3
+Dynamic: license-file
+
+# hodlodds-mcp
+
+A local stdio MCP server for HodlOdds crash odds. Free tools explain token
+coverage, data markets and feed status. With a local wallet configured, paid
+tools use x402 USDC on Solana or Base with per-call and per-session spending
+limits. Paying on Base does not change the data universe: current paid scores
+cover active SOL-quoted pump.fun graduates.
+
+## Install
+
+```sh
+pip install hodlodds-mcp
+hodlodds-mcp
+# Or run in an isolated environment:
+uvx hodlodds-mcp
+```
+
+Python 3.11+ is required. Dependencies are `hodlodds>=0.3.0,<0.4` and
+`mcp>=2.3,<3`. The HodlOdds client supplies its pinned x402 dependencies. This
+package starts a local process, not an HTTP MCP endpoint. Stdout is reserved
+for MCP protocol messages.
+
+## Tools and prices
+
+| Tool | Cost in USDC | Result |
+| --- | --- | --- |
+| `status()` | Free | Feed state, age, source timestamp and API status fields |
+| `markets()` | Free | Available and experimental data markets, prices and filter syntax |
+| `coverage(mint)` | Free | Observed coverage stage, reason and source timestamp |
+| `meaning()` | Free, offline | Crash definition, confidence interpretation and freshness rules |
+| `crash_odds(mint)` | 0.01 per delivered answer | Crash probability, summary, confidence, forecast timestamps, receipt and budget |
+| `board(...)` | 0.005 per delivered coin; empty results free | Ranked rows or a watchlist, omitted-mint facts, timestamps, receipt and budget |
+
+The separate HTTP API's `/v1/risk/{mint}/last` costs 0.002 USDC for last-known
+odds at most 30 minutes old. **Version 0.1.0 exposes no last-known MCP tool**;
+use the Python SDK's `last()` method directly if you explicitly want that route.
+
+`board` accepts `limit`, `sort`, `max_risk`, `min_risk`, `min_liquidity_sol`,
+`min_age_min`, `max_age_min`, `min_trades_5`, `min_confidence`, `mints`, `chain`
+and `platform`. Sorts are `lowest_risk` (default), `riskiest`, `liquidity`,
+`newest` and `active`. Without `mints`, limits are 10–500 (default 50).
+With a watchlist of 1–100 distinct Solana mint addresses, the default limit is
+its length and explicit limits are 1–100. Only returned coins are charged.
+`not_delivered` contains coverage/filter facts for omitted mints, not inferred
+odds. Probability filters use 0–1; confidence is `high`, `medium` or `low`.
+
+`crash_odds`, `board` and `coverage` accept optional `chain` and `platform`
+strings, comma-separated strings or lists. Currently use `chain="solana"`
+or its CAIP-2 ID and `platform="pumpfun"`; `pump` and `pump.fun` are aliases.
+Values are case-insensitive; empty, duplicate and unsupported values are
+refused before payment. Use `markets()` to check current availability. Data
+markets and payment networks are separate choices.
+
+Every result includes “Odds, not guarantees. Not financial advice.” Errors
+have MCP `isError: true` and a structured error code. Missing confidence is
+reported as `missing`. Receipts contain public payment details, not signed
+authorizations or key contents. Spending is tracked in integer atomic USDC;
+displayed USDC amounts are exact decimal strings.
+
+## Configuration
+
+Tool arguments cannot change the wallet, recipient, payment network, endpoint
+or spending limits. Set these in the MCP process environment:
+
+| Variable | Default / requirement |
+| --- | --- |
+| `HODLODDS_BASE_URL` | `https://api.hodlodds.com`; HTTPS, or HTTP on loopback for local tests |
+| `HODLODDS_NETWORK` | `devnet`; one of `solana`, `base`, `devnet`, `base-sepolia` |
+| `HODLODDS_PAY_TO` | No default. Pin the recipient for the chosen payment network from `/v1/meta`, after independently verifying it. Required on mainnet even in read-only mode, and whenever a key is configured. |
+| `HODLODDS_KEYPAIR` | Optional local key-file path. Omit or leave empty for read-only mode. Use an absolute path in desktop configurations. |
+| `HODLODDS_MAX_PRICE_USDC` | `0.01` per call, maximum `2.5`; single-token calls retain the SDK's `1` USDC ceiling. Positive plain decimal with at most six fractional digits. |
+| `HODLODDS_SESSION_BUDGET_USDC` | Required when a key is set; positive plain decimal with at most six fractional digits. No default budget. Resets on process restart. |
+
+The default per-call cap can buy at most two delivered board rows. A larger
+offer is refused before key access; the cap does not trim an answer down to
+two coins. Set `0.50` explicitly for up to 100 delivered rows, for example.
+The accepted offer amount, not the requested limit, determines the budget debit.
+
+**Read-only mode:** omit the key and session budget. The registered tools are
+`status`, `markets`, `coverage` and `meaning`. No key is loaded at startup in
+either mode. Key files must be regular, non-symlink files, mode `0600`, at most
+4 KiB. Solana uses solana-keygen JSON; Base uses a local hex/JSON private-key
+file. Use a dedicated low-balance wallet. Never put key contents in a client
+configuration.
+
+## Client configuration
+
+Claude Desktop: merge this read-only setup into `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "hodlodds": {
+      "command": "uvx",
+      "args": ["hodlodds-mcp"]
+    }
+  }
+}
+```
+
+Use the executable's absolute path if the desktop app cannot find `uvx`.
+To enable payments, add the environment values below to that server entry.
+This is also a generic stdio process configuration for clients that accept
+`command`, `args` and `env` (adapt the surrounding configuration to your client):
+
+```json
+{
+  "command": "hodlodds-mcp",
+  "args": [],
+  "env": {
+    "HODLODDS_BASE_URL": "https://api.hodlodds.com",
+    "HODLODDS_NETWORK": "solana",
+    "HODLODDS_PAY_TO": "REPLACE_WITH_VERIFIED_RECIPIENT_FROM_META",
+    "HODLODDS_KEYPAIR": "/absolute/path/to/payer.json",
+    "HODLODDS_MAX_PRICE_USDC": "0.01",
+    "HODLODDS_SESSION_BUDGET_USDC": "0.10"
+  }
+}
+```
+
+Replace the recipient and file-path placeholders before starting. The example
+uses real mainnet USDC. For Base payments, choose `base`, its recipient and an
+EVM key file. Test networks require a test API that offers that network:
+use `devnet` or `base-sepolia`, test USDC and the matching verified recipient.
+These snippets are configuration templates; assistant applications were not
+launched during offline package testing.
+
+Restart the MCP process after changing its environment. Reconcile any uncertain
+payment first: a restart also resets the session budget.
+
+## Payment safety and reconciliation
+
+Paid calls are serialized across tools. The SDK validates the offer's network,
+asset, pinned recipient, query binding and amount before key access or signing.
+The session budget checks that exact accepted amount, then reserves it before
+the authorized request. A successful receipt retains the debit. Exhausting the
+budget refuses the next payment before signing; free tools remain available.
+
+A refusal marked `HodlOdds-Charged: no` is free only when the receipt does not
+indicate success or a transaction. A conflicting or malformed receipt remains
+uncertain. Confirmed free refusals refund the reservation, return an error and
+leave payments enabled.
+
+After an uncertain payment—such as a lost response, missing receipt or
+conflicting receipt—**all further paid calls pause**. The reserved amount stays
+spent until the operator reconciles it against finalized wallet history and
+payment records. The result includes public reconciliation details. There is
+no tool to clear the pause, no automatic retry or redemption, and no pending
+authorization file is written. Restart only after reconciliation and choose a
+new budget that accounts for prior spending.
+
+The budget is local to one process and is not shared or persistent. **Every
+restart resets it.** The paid request timeout is 90 seconds. Cancellation does
+not abandon in-flight payment accounting. A settled answer with an unexpected
+shape returns raw data with a warning instead of authorizing another payment.
+Receipts report server settlement; they are not independent proof of finality.
+
+## Meaning and freshness
+
+0.04 means about 4 in 100 tokens like this one lose 90% or more of their price within the next 60 minutes. Higher means riskier, but a low number does not mean safe: smaller or slower drops are not counted, and the odds change minute by minute.
+
+Scores are recomputed every 60 seconds, about 20 seconds after each minute closes, from completed one-minute bars up to `as_of`. Each score covers the 60 minutes after its `as_of` time and is valid only until the next update; the odds for the same token can rise sharply from one minute to the next. Scoring starts around :20; computation and publication can delay availability. For decisions, refresh immediately before acting and once per minute for continuous monitoring, checking `as_of` for a new minute. The API freshness cutoff is separate: by default, data becomes `stale` more than 120 seconds after `issued_at` or after `expires_at`. A new request does not restart the forecast window.
+
+A crash is a completed one-minute close in SOL at least 90% below the reference
+price within the displayed 60-minute window. `as_of` and `horizon_end` are UTC
+Unix seconds. Confidence describes historical calibration and evidence; it is
+not a token-specific interval or guarantee. Missing odds, missing confidence,
+stale data and uncovered tokens are not safety signals. Very low odds say
+“under 0.1%”, never a rounded zero.
+
+Odds, not guarantees. Not financial advice.
+
+## Development
+
+From the public repository root, with the dependencies and pytest installed:
+
+```sh
+python -m pytest -q mcp/tests
+python -m build mcp
+```
+
+Tests use the installed public HodlOdds package, mocked HTTP and signing, and
+an in-memory MCP session. Socket connections and DNS lookups are disabled.
+They do not prove live settlement or desktop-client integration. The budget
+adapter uses the SDK's watch accounting hook, so the dependency is bounded to
+`hodlodds>=0.3.0,<0.4` and tested before upgrades.
+
+`server.json` contains registry metadata for `com.hodlodds/hodlodds-mcp`.
+Publishing to PyPI and publishing a registry listing are separate steps;
+namespace ownership and registry acceptance must be verified by the publisher.

hodlodds_mcp-0.1.0/README.md

@@ -0,0 +1,190 @@
+# hodlodds-mcp
+
+A local stdio MCP server for HodlOdds crash odds. Free tools explain token
+coverage, data markets and feed status. With a local wallet configured, paid
+tools use x402 USDC on Solana or Base with per-call and per-session spending
+limits. Paying on Base does not change the data universe: current paid scores
+cover active SOL-quoted pump.fun graduates.
+
+## Install
+
+```sh
+pip install hodlodds-mcp
+hodlodds-mcp
+# Or run in an isolated environment:
+uvx hodlodds-mcp
+```
+
+Python 3.11+ is required. Dependencies are `hodlodds>=0.3.0,<0.4` and
+`mcp>=2.3,<3`. The HodlOdds client supplies its pinned x402 dependencies. This
+package starts a local process, not an HTTP MCP endpoint. Stdout is reserved
+for MCP protocol messages.
+
+## Tools and prices
+
+| Tool | Cost in USDC | Result |
+| --- | --- | --- |
+| `status()` | Free | Feed state, age, source timestamp and API status fields |
+| `markets()` | Free | Available and experimental data markets, prices and filter syntax |
+| `coverage(mint)` | Free | Observed coverage stage, reason and source timestamp |
+| `meaning()` | Free, offline | Crash definition, confidence interpretation and freshness rules |
+| `crash_odds(mint)` | 0.01 per delivered answer | Crash probability, summary, confidence, forecast timestamps, receipt and budget |
+| `board(...)` | 0.005 per delivered coin; empty results free | Ranked rows or a watchlist, omitted-mint facts, timestamps, receipt and budget |
+
+The separate HTTP API's `/v1/risk/{mint}/last` costs 0.002 USDC for last-known
+odds at most 30 minutes old. **Version 0.1.0 exposes no last-known MCP tool**;
+use the Python SDK's `last()` method directly if you explicitly want that route.
+
+`board` accepts `limit`, `sort`, `max_risk`, `min_risk`, `min_liquidity_sol`,
+`min_age_min`, `max_age_min`, `min_trades_5`, `min_confidence`, `mints`, `chain`
+and `platform`. Sorts are `lowest_risk` (default), `riskiest`, `liquidity`,
+`newest` and `active`. Without `mints`, limits are 10–500 (default 50).
+With a watchlist of 1–100 distinct Solana mint addresses, the default limit is
+its length and explicit limits are 1–100. Only returned coins are charged.
+`not_delivered` contains coverage/filter facts for omitted mints, not inferred
+odds. Probability filters use 0–1; confidence is `high`, `medium` or `low`.
+
+`crash_odds`, `board` and `coverage` accept optional `chain` and `platform`
+strings, comma-separated strings or lists. Currently use `chain="solana"`
+or its CAIP-2 ID and `platform="pumpfun"`; `pump` and `pump.fun` are aliases.
+Values are case-insensitive; empty, duplicate and unsupported values are
+refused before payment. Use `markets()` to check current availability. Data
+markets and payment networks are separate choices.
+
+Every result includes “Odds, not guarantees. Not financial advice.” Errors
+have MCP `isError: true` and a structured error code. Missing confidence is
+reported as `missing`. Receipts contain public payment details, not signed
+authorizations or key contents. Spending is tracked in integer atomic USDC;
+displayed USDC amounts are exact decimal strings.
+
+## Configuration
+
+Tool arguments cannot change the wallet, recipient, payment network, endpoint
+or spending limits. Set these in the MCP process environment:
+
+| Variable | Default / requirement |
+| --- | --- |
+| `HODLODDS_BASE_URL` | `https://api.hodlodds.com`; HTTPS, or HTTP on loopback for local tests |
+| `HODLODDS_NETWORK` | `devnet`; one of `solana`, `base`, `devnet`, `base-sepolia` |
+| `HODLODDS_PAY_TO` | No default. Pin the recipient for the chosen payment network from `/v1/meta`, after independently verifying it. Required on mainnet even in read-only mode, and whenever a key is configured. |
+| `HODLODDS_KEYPAIR` | Optional local key-file path. Omit or leave empty for read-only mode. Use an absolute path in desktop configurations. |
+| `HODLODDS_MAX_PRICE_USDC` | `0.01` per call, maximum `2.5`; single-token calls retain the SDK's `1` USDC ceiling. Positive plain decimal with at most six fractional digits. |
+| `HODLODDS_SESSION_BUDGET_USDC` | Required when a key is set; positive plain decimal with at most six fractional digits. No default budget. Resets on process restart. |
+
+The default per-call cap can buy at most two delivered board rows. A larger
+offer is refused before key access; the cap does not trim an answer down to
+two coins. Set `0.50` explicitly for up to 100 delivered rows, for example.
+The accepted offer amount, not the requested limit, determines the budget debit.
+
+**Read-only mode:** omit the key and session budget. The registered tools are
+`status`, `markets`, `coverage` and `meaning`. No key is loaded at startup in
+either mode. Key files must be regular, non-symlink files, mode `0600`, at most
+4 KiB. Solana uses solana-keygen JSON; Base uses a local hex/JSON private-key
+file. Use a dedicated low-balance wallet. Never put key contents in a client
+configuration.
+
+## Client configuration
+
+Claude Desktop: merge this read-only setup into `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "hodlodds": {
+      "command": "uvx",
+      "args": ["hodlodds-mcp"]
+    }
+  }
+}
+```
+
+Use the executable's absolute path if the desktop app cannot find `uvx`.
+To enable payments, add the environment values below to that server entry.
+This is also a generic stdio process configuration for clients that accept
+`command`, `args` and `env` (adapt the surrounding configuration to your client):
+
+```json
+{
+  "command": "hodlodds-mcp",
+  "args": [],
+  "env": {
+    "HODLODDS_BASE_URL": "https://api.hodlodds.com",
+    "HODLODDS_NETWORK": "solana",
+    "HODLODDS_PAY_TO": "REPLACE_WITH_VERIFIED_RECIPIENT_FROM_META",
+    "HODLODDS_KEYPAIR": "/absolute/path/to/payer.json",
+    "HODLODDS_MAX_PRICE_USDC": "0.01",
+    "HODLODDS_SESSION_BUDGET_USDC": "0.10"
+  }
+}
+```
+
+Replace the recipient and file-path placeholders before starting. The example
+uses real mainnet USDC. For Base payments, choose `base`, its recipient and an
+EVM key file. Test networks require a test API that offers that network:
+use `devnet` or `base-sepolia`, test USDC and the matching verified recipient.
+These snippets are configuration templates; assistant applications were not
+launched during offline package testing.
+
+Restart the MCP process after changing its environment. Reconcile any uncertain
+payment first: a restart also resets the session budget.
+
+## Payment safety and reconciliation
+
+Paid calls are serialized across tools. The SDK validates the offer's network,
+asset, pinned recipient, query binding and amount before key access or signing.
+The session budget checks that exact accepted amount, then reserves it before
+the authorized request. A successful receipt retains the debit. Exhausting the
+budget refuses the next payment before signing; free tools remain available.
+
+A refusal marked `HodlOdds-Charged: no` is free only when the receipt does not
+indicate success or a transaction. A conflicting or malformed receipt remains
+uncertain. Confirmed free refusals refund the reservation, return an error and
+leave payments enabled.
+
+After an uncertain payment—such as a lost response, missing receipt or
+conflicting receipt—**all further paid calls pause**. The reserved amount stays
+spent until the operator reconciles it against finalized wallet history and
+payment records. The result includes public reconciliation details. There is
+no tool to clear the pause, no automatic retry or redemption, and no pending
+authorization file is written. Restart only after reconciliation and choose a
+new budget that accounts for prior spending.
+
+The budget is local to one process and is not shared or persistent. **Every
+restart resets it.** The paid request timeout is 90 seconds. Cancellation does
+not abandon in-flight payment accounting. A settled answer with an unexpected
+shape returns raw data with a warning instead of authorizing another payment.
+Receipts report server settlement; they are not independent proof of finality.
+
+## Meaning and freshness
+
+0.04 means about 4 in 100 tokens like this one lose 90% or more of their price within the next 60 minutes. Higher means riskier, but a low number does not mean safe: smaller or slower drops are not counted, and the odds change minute by minute.
+
+Scores are recomputed every 60 seconds, about 20 seconds after each minute closes, from completed one-minute bars up to `as_of`. Each score covers the 60 minutes after its `as_of` time and is valid only until the next update; the odds for the same token can rise sharply from one minute to the next. Scoring starts around :20; computation and publication can delay availability. For decisions, refresh immediately before acting and once per minute for continuous monitoring, checking `as_of` for a new minute. The API freshness cutoff is separate: by default, data becomes `stale` more than 120 seconds after `issued_at` or after `expires_at`. A new request does not restart the forecast window.
+
+A crash is a completed one-minute close in SOL at least 90% below the reference
+price within the displayed 60-minute window. `as_of` and `horizon_end` are UTC
+Unix seconds. Confidence describes historical calibration and evidence; it is
+not a token-specific interval or guarantee. Missing odds, missing confidence,
+stale data and uncovered tokens are not safety signals. Very low odds say
+“under 0.1%”, never a rounded zero.
+
+Odds, not guarantees. Not financial advice.
+
+## Development
+
+From the public repository root, with the dependencies and pytest installed:
+
+```sh
+python -m pytest -q mcp/tests
+python -m build mcp
+```
+
+Tests use the installed public HodlOdds package, mocked HTTP and signing, and
+an in-memory MCP session. Socket connections and DNS lookups are disabled.
+They do not prove live settlement or desktop-client integration. The budget
+adapter uses the SDK's watch accounting hook, so the dependency is bounded to
+`hodlodds>=0.3.0,<0.4` and tested before upgrades.
+
+`server.json` contains registry metadata for `com.hodlodds/hodlodds-mcp`.
+Publishing to PyPI and publishing a registry listing are separate steps;
+namespace ownership and registry acceptance must be verified by the publisher.

hodlodds_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hodlodds-mcp"
+version = "0.1.0"
+description = "Local stdio MCP tools for HodlOdds crash odds with bounded USDC payments"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+dependencies = ["hodlodds>=0.3.0,<0.4", "mcp>=2.3,<3"]
+
+[project.scripts]
+hodlodds-mcp = "hodlodds_mcp.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

hodlodds_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hodlodds_mcp-0.1.0/src/hodlodds_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""HodlOdds local MCP server."""
+
+__version__ = "0.1.0"