@pmxt/mcp 2.29.0 → 2.30.2

package/LICENSE

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

package/README.md

@@ -0,0 +1,111 @@
+# @pmxt/mcp
+
+MCP server that exposes the [PMXT](https://pmxt.dev) unified prediction market API as tools for Claude and other AI agents.
+
+One tool per API method. Same interface regardless of venue -- Polymarket, Kalshi, Limitless, Probable, Baozi, Myriad, Opinion, Metaculus, Smarkets, and more.
+
+## Quick start
+
+Add to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "pmxt": {
+      "command": "npx",
+      "args": ["-y", "@pmxt/mcp"],
+      "env": {
+        "PMXT_API_KEY": "pmxt_live_..."
+      }
+    }
+  }
+}
+```
+
+Or run directly:
+
+```sh
+PMXT_API_KEY=pmxt_live_... npx @pmxt/mcp
+```
+
+Get an API key at [pmxt.dev/dashboard](https://pmxt.dev/dashboard).
+
+## Modes
+
+The MCP server doesn't run prediction market logic itself -- it forwards every tool call to a PMXT API server over HTTP. Where that server lives depends on the mode:
+
+**Hosted** -- Set `PMXT_API_KEY` and the server calls `https://api.pmxt.dev`. No local setup required; the hosted service manages exchange connections, caching, and rate limits for you.
+
+**Local (sidecar)** -- If no API key is set, the server assumes you're running the PMXT core server locally on `http://localhost:3847`. This is useful for development, self-hosting, or when you want full control over the runtime. See the [pmxt core repo](https://github.com/pmxt-dev/pmxt) for how to run the server.
+
+You can point at any PMXT-compatible server by setting `PMXT_API_URL` explicitly.
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `PMXT_API_KEY` | API key for the hosted PMXT service |
+| `PMXT_API_URL` | Override the API base URL (defaults based on mode) |
+
+## Tools
+
+Every tool requires an `exchange` parameter (e.g. `polymarket`, `kalshi`, `limitless`). Read-only tools are safe to call freely. Order-related tools (`createOrder`, `submitOrder`, `cancelOrder`) require explicit user confirmation -- they spend real money.
+
+**Market discovery:** `fetchMarkets`, `fetchMarketsPaginated`, `fetchEvents`, `fetchEvent`, `fetchMarket`
+
+**Order book & pricing:** `fetchOrderBook`, `fetchTrades`, `fetchOHLCV`, `getExecutionPrice`, `getExecutionPriceDetailed`
+
+**Trading:** `buildOrder`, `createOrder`, `submitOrder`, `cancelOrder`
+
+**Account:** `fetchBalance`, `fetchPositions`, `fetchOpenOrders`, `fetchClosedOrders`, `fetchAllOrders`, `fetchOrder`, `fetchMyTrades`, `loadMarkets`
+
+## How it works
+
+The server translates MCP tool calls into HTTP requests to the PMXT REST API:
+
+1. Agent calls a tool (e.g. `fetchMarkets`) with flat `{ exchange, limit, query }` input
+2. The server reconstructs positional arguments from the flat input using embedded arg specs
+3. Sends `POST /api/{exchange}/{method}` with `{ args: [...] }` to the PMXT API
+4. Returns the JSON response to the agent
+
+## Auto-generation pipeline
+
+The tool definitions in `src/generated/tools.ts` are **not hand-written**. They are generated from the PMXT core OpenAPI spec by `scripts/generate-tools.cjs`.
+
+The full pipeline runs automatically on every PMXT release:
+
+1. A new version tag (`v*`) is pushed to the [pmxt core repo](https://github.com/pmxt-dev/pmxt)
+2. The [`sync-mcp.yml`](https://github.com/pmxt-dev/pmxt/blob/main/.github/workflows/sync-mcp.yml) GitHub Actions workflow triggers
+3. It clones this repo, copies the latest spec files from core into `spec/`:
+   - [`core/src/server/openapi.yaml`](https://github.com/pmxt-dev/pmxt/blob/main/core/src/server/openapi.yaml) -- full API spec (endpoints, parameters, response schemas)
+   - [`core/src/server/method-verbs.json`](https://github.com/pmxt-dev/pmxt/blob/main/core/src/server/method-verbs.json) -- HTTP verb and positional argument metadata per method
+4. Runs `node scripts/generate-tools.cjs` to regenerate `src/generated/tools.ts`
+5. Bumps `package.json` to match the core version
+6. Commits, tags, and pushes to this repo
+7. Publishes to npm with `npm publish --provenance --access public`
+
+**What the generator does:**
+- Reads both spec files
+- Skips streaming/internal methods (`watchOrderBook`, `close`, `healthCheck`, etc.)
+- Flattens complex parameters into flat MCP tool input schemas
+- Embeds `ArgSpec` metadata so the server can reconstruct positional args at runtime
+- Adds annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`) per tool
+- Marks order-related tools with a `credentials` input property
+
+To regenerate locally:
+
+```sh
+npm run generate
+```
+
+## Development
+
+```sh
+npm install
+npm run generate   # regenerate tools from spec/
+npm run build      # compile TypeScript
+```
+
+## License
+
+MIT

package/dist/generated/tools.js

@@ -650,7 +650,7 @@ export const TOOLS = [
     },
     {
         "name": "fetchEvents",
-        "description": "Fetch events with optional keyword search. Events group related markets together (e.g., \"Who will be Fed Chair?\" contains multiple candidate markets).",
+        "description": "Start here for discovery and search. Events are the top-level grouping in the data model: Event -> Market -> Outcome. An event is a broad topic (e.g., \"Who will win the 2028 presidential election?\"), a market is a specific tradeable question within that event (e.g., \"Will Kamala Harris win the 2028 presidential election?\"), and an outcome is the side you buy (e.g., \"Yes\" or \"No\"). When a user asks to \"find\", \"search for\", or \"look up\" a market, use this tool — they almost always mean the event-level topic. Each returned event includes its child markets. Supports optional keyword search, filtering, and pagination.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -844,7 +844,7 @@ export const TOOLS = [
     },
     {
         "name": "fetchMarkets",
-        "description": "Fetch markets with optional filtering, search, or slug lookup. Always hits the exchange API — results reflect the live state at the time of the call.",
+        "description": "Fetch individual tradeable contracts (markets). A market is a specific question like \"Will Kamala Harris win the 2028 presidential election?\" — for general discovery or search, prefer fetchEvents instead, which returns the higher-level topic (e.g., \"Who will win the 2028 presidential election?\") with all its markets grouped together. When users say \"search for a market\" they almost always mean an event. Use fetchMarkets when you need a specific contract by ID/slug, or when you already have an eventId and want its child markets. Always hits the exchange API — results reflect the live state at the time of the call.",
         "inputSchema": {
             "type": "object",
             "properties": {

package/dist/server.js

@@ -14,6 +14,12 @@ Same methods, same response shape, regardless of venue.
 
 SETUP: Get an API key at pmxt.dev/dashboard. Set PMXT_API_KEY in your environment.
 
+DATA MODEL (Event -> Market -> Outcome):
+- Event: a broad topic, e.g. "Who will win the 2028 presidential election?"
+- Market: a specific tradeable question within an event, e.g. "Will Kamala Harris win the 2028 presidential election?"
+- Outcome: the side you buy or sell, e.g. "Yes" (she wins) or "No" (she does not win).
+When users say "market" they almost always mean an event. Use fetchEvents for discovery and search.
+
 IMPORTANT RULES:
 - NEVER place orders (createOrder, submitOrder) without explicit user confirmation. \
 These spend real money. Always show the user the order details (venue, market, side, price, amount) and wait for approval.
@@ -22,10 +28,12 @@ These spend real money. Always show the user the order details (venue, market, s
 - Venue credentials (privateKey, apiKey) are sensitive. Never log or display them.
 
 WORKFLOW:
-1. Use fetchMarkets or fetchEvents to discover markets (use the "query" param for search).
-2. Use fetchOrderBook to check liquidity and prices.
-3. Use getExecutionPrice to quote a trade before placing it.
-4. Use buildOrder to preview, then submitOrder to execute (with user approval).
+1. Use fetchEvents to discover and search for topics (use the "query" param). This is the right starting point \
+even when the user says "market" -- they almost always mean an event. Each event includes its child markets.
+2. Use fetchMarkets only when you need a specific contract by ID/slug, or to list markets within a known event.
+3. Use fetchOrderBook to check liquidity and prices.
+4. Use getExecutionPrice to quote a trade before placing it.
+5. Use buildOrder to preview, then submitOrder to execute (with user approval).
 
 The "exchange" param is required on every call. Options: polymarket, kalshi, limitless, probable, etc.`;
 export function createServer(config) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmxt/mcp",
-  "version": "2.29.0",
+  "version": "2.30.2",
   "description": "MCP server for PMXT - the unified prediction market API",
   "type": "module",
   "bin": {