worm-mcp 0.1.0__tar.gz

worm_mcp-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pypirc
+.idea/
+.vscode/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.DS_Store
+.env
+.env.local

worm_mcp-0.1.0/LICENSE

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

worm_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: worm-mcp
+Version: 0.1.0
+Summary: MCP server for Worm prediction markets on Solana
+Project-URL: Homepage, https://worm.wtf
+Project-URL: Documentation, https://docs.worm.wtf
+Project-URL: Repository, https://github.com/wormwtf/worm-mcp
+Project-URL: Issues, https://github.com/wormwtf/worm-mcp/issues
+Author-email: Worm <support@worm.wtf>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: mcp,prediction-markets,solana,trading,worm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: worm-sdk[signing]>=0.9.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="https://www.worm.wtf/images/logo.png" alt="Worm" width="110px" />
+  <h1>Worm MCP</h1>
+  <p>Browse, trade, and manage prediction markets from any AI agent.</p>
+  <p>
+    🌐 <a href="https://worm.wtf">Worm</a> &nbsp;·&nbsp;
+    📖 <a href="https://docs.worm.wtf">Docs</a> &nbsp;·&nbsp;
+    📦 <a href="https://github.com/wormwtf/worm-sdk">worm-sdk</a> &nbsp;·&nbsp;
+    🐛 <a href="https://github.com/wormwtf/worm-mcp/issues">Issues</a> &nbsp;·&nbsp;
+    ⚖️ <a href="LICENSE">MIT</a>
+  </p>
+  <p>
+    <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+" /></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+  </p>
+</div>
+
+## Installation
+
+worm-mcp runs over stdio; your MCP client launches it on demand. Set `WALLET_PRIVATE_KEY` to enable authenticated and trading tools, or omit it to use only the public, read-only tools.
+
+Pick the flow that fits you:
+
+- **[For users](#for-users)**: you just want to use the tool in your MCP client. Your client launches it with `uvx`; no manual install.
+- **[For developers](#for-developers)**: you want to modify the code. Clone the repo and run it from a local editable install.
+
+### For users
+
+Your client launches worm-mcp on demand; `uvx` fetches and runs it for you.
+
+**Claude Code**: register it once from the CLI; `--scope user` makes it available in every project:
+
+```bash
+claude mcp add --scope user worm \
+  -e WALLET_PRIVATE_KEY=<base58-solana-private-key> \
+  -- uvx worm-mcp
+```
+
+Confirm with `claude mcp list` (shows `worm … ✓ Connected`).
+
+**Cursor**: add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project), then enable it under **Settings → MCP**:
+
+```json
+{
+  "mcpServers": {
+    "worm": {
+      "command": "uvx",
+      "args": ["worm-mcp"],
+      "env": { "WALLET_PRIVATE_KEY": "<base58-solana-private-key>" }
+    }
+  }
+}
+```
+
+**Claude Desktop**: **Settings → Developer → Edit Config** opens `claude_desktop_config.json`; add the same `mcpServers` block and restart the app.
+
+**Smithery**: [Smithery](https://smithery.ai) installs it into a supported client with one command (it runs locally over stdio, so your key stays on your machine):
+
+```bash
+npx -y @smithery/cli install worm-mcp --client claude
+```
+
+**Other clients** (Windsurf, Cline, Zed, VS Code, …): same launch: command `uvx`, args `["worm-mcp"]`, plus the `WALLET_PRIVATE_KEY` env. Only the config file location differs.
+
+> No `uv`? `pipx run worm-mcp` or `pip install worm-mcp` work too.
+
+### For developers
+
+Run worm-mcp from a local clone, for hacking on the code or running an unpublished build. Clone and set up an editable environment:
+
+```bash
+git clone https://github.com/wormwtf/worm-mcp.git
+cd worm-mcp
+uv venv
+uv pip install -e ".[dev]"
+uv run ruff check src
+WALLET_PRIVATE_KEY=... worm-mcp     # run the stdio server directly
+```
+
+Point your client at the editable checkout so code changes take effect on the next client restart. Either add `--with-editable` to the uvx launch:
+
+```bash
+claude mcp add --scope user worm \
+  -e WALLET_PRIVATE_KEY=<base58-solana-private-key> \
+  -- uvx --from /path/to/worm-mcp --with-editable /path/to/worm-mcp worm-mcp
+```
+
+…or point the client's `command` straight at the venv binary the editable install creates (`args` can be omitted):
+
+```json
+{
+  "mcpServers": {
+    "worm": {
+      "command": "/path/to/worm-mcp/.venv/bin/worm-mcp",
+      "env": { "WALLET_PRIVATE_KEY": "<base58-solana-private-key>" }
+    }
+  }
+}
+```
+
+## Verify
+
+Ask your client *"List trending markets on Worm"* (public) or *"What's my Worm account summary?"* (confirms auth): a sensible answer means it's wired up.
+
+## Requirements
+
+- An MCP client (Claude Code, Cursor, Claude Desktop, …)
+- [`uv`](https://docs.astral.sh/uv/) (or `pipx` / `pip`)
+- A funded Solana wallet (only for trading and other authenticated tools)
+
+## Environment variables
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `WALLET_PRIVATE_KEY` | for writes | Base58 Solana private key (the export from Phantom/Solflare; a 64-byte hex keypair also works). Signs transactions locally and bootstraps HMAC credentials on first run, cached in `~/.worm/config.json`. |
+| `WORM_API_KEY` / `WORM_API_SECRET` | no | Use existing HMAC credentials instead of bootstrapping |
+| `WORM_API_BASE` | no | API base URL (default `https://api.worm.wtf`) |
+
+## Tools
+
+### Public (no credentials)
+
+| Tool | Description |
+|---|---|
+| `search` | Search markets and events by text and filters |
+| `list_markets` | Browse markets by category, state, or sort |
+| `get_market` | Full market detail (outcomes, fees, config, state) |
+| `get_market_stats` | Volume, market cap, and trade count |
+| `get_market_price` | Mid-price snapshot for an outcome |
+| `get_orderbook` | Spot orderbook bids and asks |
+| `get_market_candles` | OHLCV candles (5m / 30m) |
+| `get_market_trades` | Recent public trades |
+| `get_market_margin_activity` | Public margin activity feed |
+| `list_events` | Browse events (groups of related markets) |
+| `get_event` | Full event detail with all markets |
+| `list_sports` | Sports and leagues catalog |
+| `estimate_margin_position` | Preview a leveraged position |
+| `read_worm_docs` | Fetch Worm documentation pages |
+
+### Authenticated read (HMAC)
+
+| Tool | Description |
+|---|---|
+| `get_account_summary` | Your profile |
+| `get_account_assets` | Portfolio share balances |
+| `get_account_pnl` | PnL breakdown |
+| `list_orders` / `get_order` | Your spot orders |
+| `list_trades` | Your trade fills |
+| `list_margin_positions` / `get_margin_position` | Your margin positions |
+| `list_margin_requests` / `get_margin_request` | Your margin position requests |
+| `list_margin_settlements` | Margin settlements |
+| `list_redeems` / `get_redeem` | Your redeem records |
+| `list_api_keys` | Your API keys |
+
+### Authenticated write (HMAC)
+
+| Tool | Description |
+|---|---|
+| `cancel_margin_request` | Cancel a pending margin request |
+| `close_margin_position` | Close a margin position |
+| `set_tp_sl` / `remove_tp_sl` | Set / clear take-profit and stop-loss |
+| `claim_margin_settlement` | Claim a resolved settlement |
+| `revoke_api_key` | Revoke an API key |
+
+### Authenticated write: local signing (needs `WALLET_PRIVATE_KEY`)
+
+| Tool | Description |
+|---|---|
+| `place_order` / `cancel_order` | Place / cancel a spot order |
+| `open_margin_position` | Open a leveraged position |
+| `redeem` | Redeem winnings from a resolved market |
+
+## Notes for agents
+
+- **Spot vs margin**: `place_order` is for non-margin (orderbook) markets; use `open_margin_position` when `margin_enabled=true`. Margin markets quote against an AMM, so `get_orderbook` may be empty; size with `estimate_margin_position`.
+- **Margin lifecycle**: `open_margin_position` returns a *position-request* pubkey; the actual position appears via `list_margin_positions` (match `position_request_pubkey`) once funding completes. TP/SL is unsupported on Hyperliquid-backed markets.
+- **Leverage**: always call `estimate_margin_position` and confirm with the user before opening; leverage carries liquidation risk.
+- **Docs on demand**: call `read_worm_docs` with no arguments for the index, then pass a path for exact API schemas and examples.
+
+## Features
+
+- 38 tools across markets, events, search, sports, account, orders, trades, margin, redeems, key management, and docs
+- Local Solana keypair signing, so your private key never leaves the MCP process
+- Auto-bootstrapped HMAC credentials: set one env var and the rest is automatic
+- Public market data works with no credentials at all
+- Built on the official [`worm-sdk`](https://pypi.org/project/worm-sdk/), with full type hints
+
+## Architecture
+
+```
+┌──────────────┐  stdio   ┌────────────┐  HTTPS + HMAC  ┌──────────────┐
+│  MCP client  │ ◀──────▶ │  worm-mcp  │ ◀────────────▶ │  Worm API    │
+│ (Claude etc.)│          │  (Python)  │                │ api.worm.wtf │
+└──────────────┘          └─────┬──────┘                └──────────────┘
+                                │ ed25519 signing (orders, margin, redeems)
+                                ▼
+                          worm-sdk + solders (local keypair)
+```
+
+See [rate limits](https://docs.worm.wtf/api-reference/rate-limits) in the docs. Markets are viewable at `https://worm.wtf/market/{condition_id}`.
+
+## Security
+
+- Your private key is used only to sign transactions locally; it is never sent to the Worm API or any third party.
+- Bootstrapped HMAC credentials are cached at `~/.worm/config.json` with `0600` permissions, keyed by API base URL and wallet, so multiple wallets or environments (e.g. `WORM_API_BASE` overrides) each keep their own credentials instead of clobbering one another. Writes are atomic and locked, so concurrent clients can't corrupt or lose cached credentials.
+- Use a dedicated wallet funded with only what you intend to trade, and keep the key out of version control and shared configs.
+
+## Troubleshooting
+
+- **`uvx: command not found`**: install [`uv`](https://docs.astral.sh/uv/), or use `pipx run worm-mcp` / `pip install worm-mcp`.
+- **Tools don't appear**: fully restart the client; it spawns the server once at startup. In Claude Code, check `claude mcp list`.
+- **Authentication errors**: confirm `WALLET_PRIVATE_KEY` is a valid base58 Solana key; delete `~/.worm/config.json` to force a fresh credential bootstrap.

worm_mcp-0.1.0/README.md

@@ -0,0 +1,212 @@
+<div align="center">
+  <img src="https://www.worm.wtf/images/logo.png" alt="Worm" width="110px" />
+  <h1>Worm MCP</h1>
+  <p>Browse, trade, and manage prediction markets from any AI agent.</p>
+  <p>
+    🌐 <a href="https://worm.wtf">Worm</a> &nbsp;·&nbsp;
+    📖 <a href="https://docs.worm.wtf">Docs</a> &nbsp;·&nbsp;
+    📦 <a href="https://github.com/wormwtf/worm-sdk">worm-sdk</a> &nbsp;·&nbsp;
+    🐛 <a href="https://github.com/wormwtf/worm-mcp/issues">Issues</a> &nbsp;·&nbsp;
+    ⚖️ <a href="LICENSE">MIT</a>
+  </p>
+  <p>
+    <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+" /></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+  </p>
+</div>
+
+## Installation
+
+worm-mcp runs over stdio; your MCP client launches it on demand. Set `WALLET_PRIVATE_KEY` to enable authenticated and trading tools, or omit it to use only the public, read-only tools.
+
+Pick the flow that fits you:
+
+- **[For users](#for-users)**: you just want to use the tool in your MCP client. Your client launches it with `uvx`; no manual install.
+- **[For developers](#for-developers)**: you want to modify the code. Clone the repo and run it from a local editable install.
+
+### For users
+
+Your client launches worm-mcp on demand; `uvx` fetches and runs it for you.
+
+**Claude Code**: register it once from the CLI; `--scope user` makes it available in every project:
+
+```bash
+claude mcp add --scope user worm \
+  -e WALLET_PRIVATE_KEY=<base58-solana-private-key> \
+  -- uvx worm-mcp
+```
+
+Confirm with `claude mcp list` (shows `worm … ✓ Connected`).
+
+**Cursor**: add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project), then enable it under **Settings → MCP**:
+
+```json
+{
+  "mcpServers": {
+    "worm": {
+      "command": "uvx",
+      "args": ["worm-mcp"],
+      "env": { "WALLET_PRIVATE_KEY": "<base58-solana-private-key>" }
+    }
+  }
+}
+```
+
+**Claude Desktop**: **Settings → Developer → Edit Config** opens `claude_desktop_config.json`; add the same `mcpServers` block and restart the app.
+
+**Smithery**: [Smithery](https://smithery.ai) installs it into a supported client with one command (it runs locally over stdio, so your key stays on your machine):
+
+```bash
+npx -y @smithery/cli install worm-mcp --client claude
+```
+
+**Other clients** (Windsurf, Cline, Zed, VS Code, …): same launch: command `uvx`, args `["worm-mcp"]`, plus the `WALLET_PRIVATE_KEY` env. Only the config file location differs.
+
+> No `uv`? `pipx run worm-mcp` or `pip install worm-mcp` work too.
+
+### For developers
+
+Run worm-mcp from a local clone, for hacking on the code or running an unpublished build. Clone and set up an editable environment:
+
+```bash
+git clone https://github.com/wormwtf/worm-mcp.git
+cd worm-mcp
+uv venv
+uv pip install -e ".[dev]"
+uv run ruff check src
+WALLET_PRIVATE_KEY=... worm-mcp     # run the stdio server directly
+```
+
+Point your client at the editable checkout so code changes take effect on the next client restart. Either add `--with-editable` to the uvx launch:
+
+```bash
+claude mcp add --scope user worm \
+  -e WALLET_PRIVATE_KEY=<base58-solana-private-key> \
+  -- uvx --from /path/to/worm-mcp --with-editable /path/to/worm-mcp worm-mcp
+```
+
+…or point the client's `command` straight at the venv binary the editable install creates (`args` can be omitted):
+
+```json
+{
+  "mcpServers": {
+    "worm": {
+      "command": "/path/to/worm-mcp/.venv/bin/worm-mcp",
+      "env": { "WALLET_PRIVATE_KEY": "<base58-solana-private-key>" }
+    }
+  }
+}
+```
+
+## Verify
+
+Ask your client *"List trending markets on Worm"* (public) or *"What's my Worm account summary?"* (confirms auth): a sensible answer means it's wired up.
+
+## Requirements
+
+- An MCP client (Claude Code, Cursor, Claude Desktop, …)
+- [`uv`](https://docs.astral.sh/uv/) (or `pipx` / `pip`)
+- A funded Solana wallet (only for trading and other authenticated tools)
+
+## Environment variables
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `WALLET_PRIVATE_KEY` | for writes | Base58 Solana private key (the export from Phantom/Solflare; a 64-byte hex keypair also works). Signs transactions locally and bootstraps HMAC credentials on first run, cached in `~/.worm/config.json`. |
+| `WORM_API_KEY` / `WORM_API_SECRET` | no | Use existing HMAC credentials instead of bootstrapping |
+| `WORM_API_BASE` | no | API base URL (default `https://api.worm.wtf`) |
+
+## Tools
+
+### Public (no credentials)
+
+| Tool | Description |
+|---|---|
+| `search` | Search markets and events by text and filters |
+| `list_markets` | Browse markets by category, state, or sort |
+| `get_market` | Full market detail (outcomes, fees, config, state) |
+| `get_market_stats` | Volume, market cap, and trade count |
+| `get_market_price` | Mid-price snapshot for an outcome |
+| `get_orderbook` | Spot orderbook bids and asks |
+| `get_market_candles` | OHLCV candles (5m / 30m) |
+| `get_market_trades` | Recent public trades |
+| `get_market_margin_activity` | Public margin activity feed |
+| `list_events` | Browse events (groups of related markets) |
+| `get_event` | Full event detail with all markets |
+| `list_sports` | Sports and leagues catalog |
+| `estimate_margin_position` | Preview a leveraged position |
+| `read_worm_docs` | Fetch Worm documentation pages |
+
+### Authenticated read (HMAC)
+
+| Tool | Description |
+|---|---|
+| `get_account_summary` | Your profile |
+| `get_account_assets` | Portfolio share balances |
+| `get_account_pnl` | PnL breakdown |
+| `list_orders` / `get_order` | Your spot orders |
+| `list_trades` | Your trade fills |
+| `list_margin_positions` / `get_margin_position` | Your margin positions |
+| `list_margin_requests` / `get_margin_request` | Your margin position requests |
+| `list_margin_settlements` | Margin settlements |
+| `list_redeems` / `get_redeem` | Your redeem records |
+| `list_api_keys` | Your API keys |
+
+### Authenticated write (HMAC)
+
+| Tool | Description |
+|---|---|
+| `cancel_margin_request` | Cancel a pending margin request |
+| `close_margin_position` | Close a margin position |
+| `set_tp_sl` / `remove_tp_sl` | Set / clear take-profit and stop-loss |
+| `claim_margin_settlement` | Claim a resolved settlement |
+| `revoke_api_key` | Revoke an API key |
+
+### Authenticated write: local signing (needs `WALLET_PRIVATE_KEY`)
+
+| Tool | Description |
+|---|---|
+| `place_order` / `cancel_order` | Place / cancel a spot order |
+| `open_margin_position` | Open a leveraged position |
+| `redeem` | Redeem winnings from a resolved market |
+
+## Notes for agents
+
+- **Spot vs margin**: `place_order` is for non-margin (orderbook) markets; use `open_margin_position` when `margin_enabled=true`. Margin markets quote against an AMM, so `get_orderbook` may be empty; size with `estimate_margin_position`.
+- **Margin lifecycle**: `open_margin_position` returns a *position-request* pubkey; the actual position appears via `list_margin_positions` (match `position_request_pubkey`) once funding completes. TP/SL is unsupported on Hyperliquid-backed markets.
+- **Leverage**: always call `estimate_margin_position` and confirm with the user before opening; leverage carries liquidation risk.
+- **Docs on demand**: call `read_worm_docs` with no arguments for the index, then pass a path for exact API schemas and examples.
+
+## Features
+
+- 38 tools across markets, events, search, sports, account, orders, trades, margin, redeems, key management, and docs
+- Local Solana keypair signing, so your private key never leaves the MCP process
+- Auto-bootstrapped HMAC credentials: set one env var and the rest is automatic
+- Public market data works with no credentials at all
+- Built on the official [`worm-sdk`](https://pypi.org/project/worm-sdk/), with full type hints
+
+## Architecture
+
+```
+┌──────────────┐  stdio   ┌────────────┐  HTTPS + HMAC  ┌──────────────┐
+│  MCP client  │ ◀──────▶ │  worm-mcp  │ ◀────────────▶ │  Worm API    │
+│ (Claude etc.)│          │  (Python)  │                │ api.worm.wtf │
+└──────────────┘          └─────┬──────┘                └──────────────┘
+                                │ ed25519 signing (orders, margin, redeems)
+                                ▼
+                          worm-sdk + solders (local keypair)
+```
+
+See [rate limits](https://docs.worm.wtf/api-reference/rate-limits) in the docs. Markets are viewable at `https://worm.wtf/market/{condition_id}`.
+
+## Security
+
+- Your private key is used only to sign transactions locally; it is never sent to the Worm API or any third party.
+- Bootstrapped HMAC credentials are cached at `~/.worm/config.json` with `0600` permissions, keyed by API base URL and wallet, so multiple wallets or environments (e.g. `WORM_API_BASE` overrides) each keep their own credentials instead of clobbering one another. Writes are atomic and locked, so concurrent clients can't corrupt or lose cached credentials.
+- Use a dedicated wallet funded with only what you intend to trade, and keep the key out of version control and shared configs.
+
+## Troubleshooting
+
+- **`uvx: command not found`**: install [`uv`](https://docs.astral.sh/uv/), or use `pipx run worm-mcp` / `pip install worm-mcp`.
+- **Tools don't appear**: fully restart the client; it spawns the server once at startup. In Claude Code, check `claude mcp list`.
+- **Authentication errors**: confirm `WALLET_PRIVATE_KEY` is a valid base58 Solana key; delete `~/.worm/config.json` to force a fresh credential bootstrap.

worm_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "worm-mcp"
+dynamic = ["version"]
+description = "MCP server for Worm prediction markets on Solana"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Worm", email = "support@worm.wtf" }]
+keywords = ["mcp", "worm", "prediction-markets", "solana", "trading"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "mcp>=1.2.0",
+    "worm-sdk[signing]>=0.9.0",
+    "httpx>=0.25",
+]
+
+[project.urls]
+Homepage = "https://worm.wtf"
+Documentation = "https://docs.worm.wtf"
+Repository = "https://github.com/wormwtf/worm-mcp"
+Issues = "https://github.com/wormwtf/worm-mcp/issues"
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.1",
+    "mypy>=1.0",
+]
+
+[project.scripts]
+worm-mcp = "worm_mcp.__main__:main"
+
+[tool.hatch.version]
+path = "src/worm_mcp/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/worm_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/worm_mcp", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"

worm_mcp-0.1.0/src/worm_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Worm MCP server."""
+
+from worm_mcp._version import __version__
+
+__all__ = ["__version__"]

worm_mcp-0.1.0/src/worm_mcp/__main__.py

@@ -0,0 +1,14 @@
+"""Entry point launched by Claude Code/Cursor/Claude Desktop as subprocess."""
+
+from __future__ import annotations
+
+from .server import build_server
+
+
+def main() -> None:
+    server = build_server()
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

worm_mcp-0.1.0/src/worm_mcp/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

worm_mcp-0.1.0/src/worm_mcp/constants.py

@@ -0,0 +1,15 @@
+"""Configuration constants for the Worm MCP server."""
+
+from pathlib import Path
+
+# Bootstrapped HMAC credentials are cached here, keyed by (base_url, wallet).
+# This path is documented in the README and MCP server instructions — keep it.
+CONFIG_FILE = Path.home() / ".worm" / "config.json"
+
+DOCS_HOST = "docs.worm.wtf"
+DOCS_BASE = f"https://{DOCS_HOST}"
+DOCS_INDEX_PATH = "llms.txt"
+DOCS_FULL_PATH = "llms-full.txt"
+
+# Cap on docs content returned by a single read_worm_docs call.
+DOCS_MAX_CHARS = 100_000

worm_mcp-0.1.0/src/worm_mcp/docs.py

@@ -0,0 +1,58 @@
+"""read_worm_docs tool — fetches Worm documentation from docs.worm.wtf via httpx."""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+import httpx
+
+from worm_mcp.constants import DOCS_BASE, DOCS_FULL_PATH, DOCS_HOST, DOCS_INDEX_PATH, DOCS_MAX_CHARS
+
+
+def _resolve_url(path: str | None, full: bool) -> str:
+    """Map (path, full) to a docs.worm.wtf URL, rejecting any other host."""
+    if full:
+        if path:
+            raise RuntimeError("Pass either a path or full=True, not both.")
+        return f"{DOCS_BASE}/{DOCS_FULL_PATH}"
+
+    # urlparse drops any query/fragment so they can't leak into the .md suffix below.
+    parsed = urlparse((path or "").strip())
+    if parsed.scheme and parsed.hostname != DOCS_HOST:
+        raise RuntimeError(f"read_worm_docs only fetches {DOCS_HOST}; got host {parsed.hostname!r}.")
+
+    rel = parsed.path.lstrip("/")
+    if not rel:  # empty path, bare "/", or a bare docs URL → index
+        return f"{DOCS_BASE}/{DOCS_INDEX_PATH}"
+    if ".." in rel.split("/"):
+        raise RuntimeError(f"Invalid docs path {path!r}.")
+    if not rel.endswith((".md", ".txt")):
+        rel = f"{rel}.md"
+    return f"{DOCS_BASE}/{rel}"
+
+
+def read_worm_docs(path: str | None = None, full: bool = False) -> dict:
+    """Fetch the docs index (no args), a doc page by path, or the full docs (full=True)."""
+    url = _resolve_url(path, full)
+    try:
+        resp = httpx.get(url, timeout=30.0, follow_redirects=True)
+    except httpx.HTTPError as e:
+        raise RuntimeError(f"Failed to fetch {url}: {e}") from e
+
+    # docs.worm.wtf uses same-host 307s (e.g. section -> intro page); follow them, but
+    # refuse the content if ANY hop (intermediate or final) left the allowlist.
+    off = next((r.url.host for r in [*resp.history, resp] if r.url.host != DOCS_HOST), None)
+    if off is not None:
+        raise RuntimeError(f"Refusing content from off-allowlist host {off!r} after redirect.")
+
+    if resp.status_code != 200:
+        raise RuntimeError(
+            f"{url} returned HTTP {resp.status_code}. "
+            "Call read_worm_docs() with no arguments to get the index of valid paths."
+        )
+
+    content = resp.text
+    truncated = len(content) > DOCS_MAX_CHARS
+    if truncated:
+        content = content[:DOCS_MAX_CHARS] + "\n\n[truncated — fetch a more specific path]"
+    return {"url": str(resp.url), "truncated": truncated, "content": content}