mcp-server-polymarket 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. mcp_server_polymarket/__init__.py +8 -0
  2. mcp_server_polymarket/__main__.py +3 -0
  3. mcp_server_polymarket/auth_flow.py +289 -0
  4. mcp_server_polymarket/capabilities.py +171 -0
  5. mcp_server_polymarket/cli.py +128 -0
  6. mcp_server_polymarket/client/__init__.py +0 -0
  7. mcp_server_polymarket/client/auth.py +62 -0
  8. mcp_server_polymarket/client/base.py +374 -0
  9. mcp_server_polymarket/client/cache.py +59 -0
  10. mcp_server_polymarket/client/endpoints.py +336 -0
  11. mcp_server_polymarket/client/paging.py +65 -0
  12. mcp_server_polymarket/client/retry.py +37 -0
  13. mcp_server_polymarket/client/session.py +156 -0
  14. mcp_server_polymarket/client/ws.py +150 -0
  15. mcp_server_polymarket/config.py +315 -0
  16. mcp_server_polymarket/coverage.py +71 -0
  17. mcp_server_polymarket/errors.py +83 -0
  18. mcp_server_polymarket/http_app.py +50 -0
  19. mcp_server_polymarket/identity.py +192 -0
  20. mcp_server_polymarket/integrations/__init__.py +0 -0
  21. mcp_server_polymarket/integrations/langgraph.py +347 -0
  22. mcp_server_polymarket/journal.py +208 -0
  23. mcp_server_polymarket/knowledge/__init__.py +41 -0
  24. mcp_server_polymarket/knowledge/concepts.md +62 -0
  25. mcp_server_polymarket/knowledge/perps.md +55 -0
  26. mcp_server_polymarket/knowledge/safety.md +63 -0
  27. mcp_server_polymarket/knowledge/trading.md +52 -0
  28. mcp_server_polymarket/logging_setup.py +18 -0
  29. mcp_server_polymarket/models/__init__.py +0 -0
  30. mcp_server_polymarket/models/base.py +146 -0
  31. mcp_server_polymarket/models/clob.py +251 -0
  32. mcp_server_polymarket/models/data.py +102 -0
  33. mcp_server_polymarket/models/gamma.py +400 -0
  34. mcp_server_polymarket/ops/__init__.py +41 -0
  35. mcp_server_polymarket/ops/account.py +326 -0
  36. mcp_server_polymarket/ops/analytics.py +544 -0
  37. mcp_server_polymarket/ops/bridge.py +229 -0
  38. mcp_server_polymarket/ops/builder.py +242 -0
  39. mcp_server_polymarket/ops/combos.py +413 -0
  40. mcp_server_polymarket/ops/discovery.py +622 -0
  41. mcp_server_polymarket/ops/docs.py +153 -0
  42. mcp_server_polymarket/ops/market_data.py +226 -0
  43. mcp_server_polymarket/ops/perps_account.py +281 -0
  44. mcp_server_polymarket/ops/perps_extras.py +187 -0
  45. mcp_server_polymarket/ops/perps_market.py +523 -0
  46. mcp_server_polymarket/ops/perps_trading.py +953 -0
  47. mcp_server_polymarket/ops/registry.py +232 -0
  48. mcp_server_polymarket/ops/rewards.py +253 -0
  49. mcp_server_polymarket/ops/sports.py +128 -0
  50. mcp_server_polymarket/ops/streams.py +343 -0
  51. mcp_server_polymarket/ops/system.py +120 -0
  52. mcp_server_polymarket/ops/trading.py +776 -0
  53. mcp_server_polymarket/ops/wallet.py +402 -0
  54. mcp_server_polymarket/prompts.py +51 -0
  55. mcp_server_polymarket/protocol.py +13 -0
  56. mcp_server_polymarket/py.typed +0 -0
  57. mcp_server_polymarket/redaction.py +66 -0
  58. mcp_server_polymarket/resources.py +44 -0
  59. mcp_server_polymarket/safety.py +224 -0
  60. mcp_server_polymarket/server.py +68 -0
  61. mcp_server_polymarket/signing/__init__.py +19 -0
  62. mcp_server_polymarket/signing/clob.py +45 -0
  63. mcp_server_polymarket/signing/eip712.py +32 -0
  64. mcp_server_polymarket/signing/orders.py +369 -0
  65. mcp_server_polymarket/signing/perps.py +322 -0
  66. mcp_server_polymarket/signing/relayer.py +235 -0
  67. mcp_server_polymarket/signing/wallets.py +121 -0
  68. mcp_server_polymarket/tools.py +191 -0
  69. mcp_server_polymarket/wallet_tx.py +265 -0
  70. mcp_server_polymarket-0.1.0.dist-info/METADATA +528 -0
  71. mcp_server_polymarket-0.1.0.dist-info/RECORD +75 -0
  72. mcp_server_polymarket-0.1.0.dist-info/WHEEL +4 -0
  73. mcp_server_polymarket-0.1.0.dist-info/entry_points.txt +3 -0
  74. mcp_server_polymarket-0.1.0.dist-info/licenses/LICENSE +21 -0
  75. mcp_server_polymarket-0.1.0.dist-info/licenses/NOTICE +28 -0
@@ -0,0 +1,8 @@
1
+ from importlib.metadata import PackageNotFoundError, version
2
+
3
+ try:
4
+ __version__ = version("mcp-server-polymarket")
5
+ except PackageNotFoundError:
6
+ __version__ = "0.0.0"
7
+
8
+ __all__ = ["__version__"]
@@ -0,0 +1,3 @@
1
+ from mcp_server_polymarket.cli import main
2
+
3
+ raise SystemExit(main())
@@ -0,0 +1,289 @@
1
+ """`mcp-server-polymarket auth` and `logout`: everything that creates or removes credentials.
2
+
3
+ Tools only use credentials. Creating them, which can onboard an account or hand a key trading
4
+ rights, happens here, in a terminal the user is watching.
5
+ """
6
+
7
+ import argparse
8
+ import getpass
9
+ import json
10
+ import secrets
11
+ import sys
12
+ import time
13
+ import uuid
14
+ from typing import Any
15
+
16
+ from mcp_server_polymarket import wallet_tx
17
+ from mcp_server_polymarket.client import endpoints as ep
18
+ from mcp_server_polymarket.client.base import ApiClient, parse_json
19
+ from mcp_server_polymarket.client.session import (
20
+ ClobCredentials,
21
+ CredentialStore,
22
+ PerpsSession,
23
+ write_private,
24
+ )
25
+ from mcp_server_polymarket.config import Settings, config_dir
26
+ from mcp_server_polymarket.errors import AuthError, ConfigError, InvalidRequest, Refused
27
+ from mcp_server_polymarket.identity import Identity, checksum
28
+ from mcp_server_polymarket.models.base import as_dict
29
+
30
+ SESSION_KEY_LIFETIME = 4_315 * 3600 # the lifetime the Relayer accepts, about 180 days
31
+ MAX_PERPS_DAYS = 30
32
+
33
+
34
+ def _say(text: str) -> None:
35
+ print(text, file=sys.stderr)
36
+
37
+
38
+ def _confirm(question: str, assume_yes: bool) -> None:
39
+ if assume_yes:
40
+ return
41
+ answer = input(f"{question} [y/N] ").strip().lower()
42
+ if answer not in ("y", "yes"):
43
+ raise Refused("Cancelled.")
44
+
45
+
46
+ def _context(settings: Settings) -> tuple[Identity, ApiClient, CredentialStore]:
47
+ from mcp_server_polymarket import signing
48
+
49
+ signing.require()
50
+ settings.register_secrets()
51
+ store = CredentialStore(settings.resolved_session_file, settings.resolved_perps_session_file)
52
+ identity = Identity(settings, store)
53
+ if identity.signer_key is None:
54
+ key = getpass.getpass("Private key of the signer (input hidden): ").strip()
55
+ if not key:
56
+ raise ConfigError("No private key given.")
57
+ settings.private_key = key # type: ignore[assignment]
58
+ identity = Identity(settings, store)
59
+ return identity, ApiClient(settings, identity), store
60
+
61
+
62
+ async def auth(args: argparse.Namespace, settings: Settings) -> int:
63
+ identity, client, store = _context(settings)
64
+ try:
65
+ if args.perps:
66
+ result = await create_perps_session(identity, client, store, args)
67
+ elif args.session_key:
68
+ result = await change_session_key(identity, client, args.session_key, True, args.yes)
69
+ elif args.revoke_session_key:
70
+ result = await change_session_key(
71
+ identity, client, args.revoke_session_key, False, args.yes
72
+ )
73
+ elif args.builder_key:
74
+ result = await create_builder_key(identity, client)
75
+ else:
76
+ result = await clob_credentials(identity, client, store)
77
+ finally:
78
+ await client.aclose()
79
+ print(json.dumps(result, indent=2))
80
+ return 0
81
+
82
+
83
+ async def clob_credentials(
84
+ identity: Identity, client: ApiClient, store: CredentialStore
85
+ ) -> dict[str, Any]:
86
+ """Derive the signer's existing CLOB API key, or create one, and store it (0600)."""
87
+ from mcp_server_polymarket.signing.clob import l1_headers
88
+
89
+ key = identity.signer_key
90
+ if key is None:
91
+ raise ConfigError("No private key configured.")
92
+ headers = l1_headers(key, int(time.time()))
93
+ response = await client.request(ep.CLOB_DERIVE_API_KEY, headers=headers, expect=(400, 404))
94
+ raw_body: Any = parse_json(response) if response.status_code == 200 else None
95
+ body = as_dict(raw_body)
96
+ created = False
97
+ if not body.get("apiKey"):
98
+ headers = l1_headers(key, int(time.time()))
99
+ body = as_dict(await client.json(ep.CLOB_CREATE_API_KEY, headers=headers))
100
+ created = True
101
+ if not body.get("apiKey"):
102
+ raise AuthError("Polymarket did not return API credentials.")
103
+ address = identity.signer_address or ""
104
+ credentials = ClobCredentials(
105
+ address=address,
106
+ api_key=str(body["apiKey"]),
107
+ secret=str(body["secret"]),
108
+ passphrase=str(body["passphrase"]),
109
+ )
110
+ store.save_clob(credentials)
111
+ return {
112
+ "status": "created" if created else "derived",
113
+ "signer": address,
114
+ "saved_to": str(store.session_file),
115
+ }
116
+
117
+
118
+ async def create_perps_session(
119
+ identity: Identity, client: ApiClient, store: CredentialStore, args: argparse.Namespace
120
+ ) -> dict[str, Any]:
121
+ """Authorise a new trading key for the signer's Perps account."""
122
+ from mcp_server_polymarket.signing import eip712
123
+ from mcp_server_polymarket.signing.perps import create_proxy_typed_data
124
+
125
+ if identity.is_session_key:
126
+ raise ConfigError(
127
+ "A Perps account is owned by an EOA; use the owner's key, not a session key."
128
+ )
129
+ owner = identity.signer_address
130
+ key = identity.signer_key
131
+ if not owner or not key:
132
+ raise ConfigError("Owner signer address and private key are required.")
133
+ days = max(1, min(int(args.days), MAX_PERPS_DAYS))
134
+ registered = as_dict(await client.json(ep.PERPS_REGISTERED, params={"address": owner}))
135
+ if not registered.get("registered"):
136
+ _say(
137
+ f"{owner} has no Perps account yet. Creating a session also opens one, which "
138
+ + "cannot be undone."
139
+ )
140
+ mode = "read-only" if args.read_only else "trading"
141
+ _confirm(f"Authorise a {mode} Perps key for {owner} for {days} days?", args.yes)
142
+ proxy_key, proxy = eip712.new_key()
143
+ now = int(time.time() * 1000)
144
+ expiry = now + days * 86_400_000
145
+ salt = secrets.randbits(32)
146
+ signature = eip712.sign(key, create_proxy_typed_data(proxy, expiry, salt, now))
147
+ label = "read-only:mcp-server-polymarket" if args.read_only else "mcp-server-polymarket"
148
+ body = {
149
+ "op": {"type": "createProxy", "args": {"expiry": expiry, "owner": owner, "proxy": proxy}},
150
+ "salt": salt,
151
+ "sig": signature,
152
+ "ts": now,
153
+ "label": label,
154
+ }
155
+ response = as_dict(await client.json(ep.PERPS_CREATE_PROXY, body=body))
156
+ secret: Any = response.get("secret")
157
+ if response.get("status") != "ok" or not secret:
158
+ raise AuthError(f"Perps refused the new key: {response.get('error') or response}")
159
+ session = PerpsSession(
160
+ owner=owner,
161
+ proxy=proxy,
162
+ secret=str(secret),
163
+ # A read-only key never needs to sign, so it is not kept.
164
+ proxy_key=None if args.read_only else proxy_key,
165
+ expires_at_ms=expiry,
166
+ label=label,
167
+ )
168
+ store.save_perps(session)
169
+ return {"status": "created", "proxy": proxy, "mode": mode, "saved_to": str(store.perps_file)}
170
+
171
+
172
+ async def change_session_key(
173
+ identity: Identity, client: ApiClient, address: str, authorize: bool, assume_yes: bool
174
+ ) -> dict[str, Any]:
175
+ """Authorise or revoke a Deposit Wallet session key, through the Relayer."""
176
+ from mcp_server_polymarket.signing import relayer
177
+
178
+ session_key = checksum(address)
179
+ _, _, wallet = wallet_tx.require_deposit_wallet(identity)
180
+ if identity.is_session_key:
181
+ raise ConfigError("Only the wallet owner can change session keys.")
182
+ valid_until = int(time.time()) + SESSION_KEY_LIFETIME
183
+ if authorize:
184
+ _confirm(
185
+ f"Let {session_key} trade from {wallet} for 180 days? It cannot withdraw.",
186
+ assume_yes,
187
+ )
188
+ call = relayer.authorize_session_signer(wallet, session_key, valid_until)
189
+ else:
190
+ _confirm(f"Revoke session key {session_key} on {wallet}?", assume_yes)
191
+ call = relayer.revoke_session_signer(wallet, session_key)
192
+ signed = await wallet_tx.sign_batch(client, identity, [call])
193
+ body: dict[str, Any] = {
194
+ "deadline": str(signed["deadline"]),
195
+ "nonce": str(signed["nonce"]),
196
+ "sessionSignerAddress": session_key,
197
+ "signature": signed["signature"],
198
+ "walletAddress": wallet,
199
+ }
200
+ if authorize:
201
+ body |= {"scopes": ["ALL"], "validUntil": str(valid_until)}
202
+ endpoint = ep.RELAYER_SESSION_AUTHORIZE if authorize else ep.RELAYER_SESSION_REVOKE
203
+ response = await client.json(
204
+ endpoint, body=body, headers={"Idempotency-Key": str(uuid.uuid4())}
205
+ )
206
+ return {"status": "submitted", "session_key": session_key, "response": response}
207
+
208
+
209
+ async def create_builder_key(identity: Identity, client: ApiClient) -> dict[str, Any]:
210
+ if identity.clob_credentials() is None:
211
+ raise ConfigError("Run `mcp-server-polymarket auth` first; builder keys need CLOB auth.")
212
+ body = as_dict(await client.json(ep.CLOB_CREATE_BUILDER_KEY))
213
+ if not body.get("key") and not body.get("apiKey"):
214
+ raise AuthError("Polymarket did not return a builder key.")
215
+ path = config_dir() / "builder_key.json"
216
+ write_private(path, body)
217
+ return {
218
+ "status": "created",
219
+ "saved_to": str(path),
220
+ "next_step": "Set POLYMARKET_BUILDER_API_KEY, _SECRET and _PASSPHRASE from that file.",
221
+ }
222
+
223
+
224
+ async def revoke_builder_key(identity: Identity, client: ApiClient) -> dict[str, Any]:
225
+ """Delete the builder API key at Polymarket, and the file `auth --builder-key` wrote."""
226
+ if identity.clob_credentials() is None:
227
+ raise ConfigError("Run `mcp-server-polymarket auth` first; builder keys need CLOB auth.")
228
+ await client.json(ep.CLOB_REVOKE_BUILDER_KEY)
229
+ path = config_dir() / "builder_key.json"
230
+ removed = path.exists()
231
+ path.unlink(missing_ok=True)
232
+ return {"status": "revoked", "removed_file": str(path) if removed else None}
233
+
234
+
235
+ async def logout(args: argparse.Namespace, settings: Settings) -> int:
236
+ settings.register_secrets()
237
+ store = CredentialStore(settings.resolved_session_file, settings.resolved_perps_session_file)
238
+ if args.perps:
239
+ session = store.load_perps()
240
+ if session is None:
241
+ print(json.dumps({"status": "no Perps session"}))
242
+ return 0
243
+ identity, client, _ = _context(settings)
244
+ try:
245
+ await revoke_perps_session(identity, client, session)
246
+ finally:
247
+ await client.aclose()
248
+ store.forget_perps()
249
+ print(json.dumps({"status": "revoked", "proxy": session.proxy}))
250
+ return 0
251
+ identity = Identity(settings, store)
252
+ if getattr(args, "builder_key", False):
253
+ client = ApiClient(settings, identity)
254
+ try:
255
+ print(json.dumps(await revoke_builder_key(identity, client)))
256
+ finally:
257
+ await client.aclose()
258
+ return 0
259
+ address = identity.clob_address
260
+ if address is None:
261
+ raise ConfigError("No signer is configured, so there is nothing to log out.")
262
+ if args.revoke:
263
+ client = ApiClient(settings, identity)
264
+ try:
265
+ await client.json(ep.CLOB_DELETE_API_KEY)
266
+ finally:
267
+ await client.aclose()
268
+ forgotten = store.forget_clob(address)
269
+ print(
270
+ json.dumps(
271
+ {"status": "forgotten" if forgotten else "nothing stored", "revoked": args.revoke}
272
+ )
273
+ )
274
+ return 0
275
+
276
+
277
+ async def revoke_perps_session(
278
+ identity: Identity, client: ApiClient, session: PerpsSession
279
+ ) -> None:
280
+ from mcp_server_polymarket.signing.perps import delete_proxy, signed_request
281
+
282
+ owner_key = identity.signer_key
283
+ if owner_key is None or (identity.signer_address or "").lower() != session.owner.lower():
284
+ raise InvalidRequest("Revoking a Perps key needs the account owner's private key.")
285
+ op = delete_proxy(session.proxy)
286
+ body = signed_request(owner_key, op, salt=secrets.randbits(32), ts_ms=int(time.time() * 1000))
287
+ response = as_dict(await client.json(ep.PERPS_DELETE_PROXY, body=body))
288
+ if response.get("status") == "err":
289
+ raise AuthError(f"Perps refused to revoke the key: {response.get('error')}")
@@ -0,0 +1,171 @@
1
+ """What this configuration can do, decided once at startup.
2
+
3
+ Every place that lists tools (the MCP server, the CLI, `auth_status` and LangGraph) uses the same
4
+ snapshot and the same `visible` function, so they cannot disagree.
5
+ """
6
+
7
+ from dataclasses import dataclass, field
8
+
9
+ from mcp_server_polymarket.config import Settings
10
+ from mcp_server_polymarket.errors import ConfigError
11
+ from mcp_server_polymarket.identity import Identity, signing_available
12
+
13
+ # Requirement name -> how to get it, shown when a tool is hidden.
14
+ REQUIREMENTS = {
15
+ "clob_l2": "CLOB API credentials: run `mcp-server-polymarket auth` or set POLYMARKET_API_KEY, "
16
+ + "POLYMARKET_API_SECRET, POLYMARKET_API_PASSPHRASE and POLYMARKET_ADDRESS",
17
+ "signer": "a signing key: set POLYMARKET_PRIVATE_KEY (or _FILE) and POLYMARKET_WALLET_ADDRESS, "
18
+ + "with the `signing` extra installed",
19
+ "owner_signer": "the wallet owner's signing key: POLYMARKET_PRIVATE_KEY and "
20
+ + "POLYMARKET_WALLET_ADDRESS, not a session key",
21
+ "relayer_key": "a Relayer API key: POLYMARKET_RELAYER_API_KEY and "
22
+ + "POLYMARKET_RELAYER_API_KEY_ADDRESS",
23
+ "perps_session": "a Perps session: run `mcp-server-polymarket auth --perps`",
24
+ "perps_signer": "a Perps session that can sign: `mcp-server-polymarket auth --perps` without "
25
+ + "--read-only",
26
+ "perps_owner": "the Perps account owner's key: POLYMARKET_PRIVATE_KEY, not a session key",
27
+ }
28
+
29
+ GATES = {
30
+ "cancel": "POLYMARKET_ALLOW_CANCEL=true (or POLYMARKET_ALLOW_TRADING=true)",
31
+ "trading": "POLYMARKET_ALLOW_TRADING=true",
32
+ "transfers": "POLYMARKET_ALLOW_TRANSFERS=true",
33
+ }
34
+
35
+ TOOLSETS = {
36
+ "discovery": "Find events, markets, tags, series, comments and profiles (Gamma)",
37
+ "market-data": "Order books, quotes and price history",
38
+ "analytics": "Positions, trades, activity, holders and leaderboards (Data API)",
39
+ "perps-market": "Perps instruments, books, candles, trades and funding",
40
+ "system": "Service status and what this server can do",
41
+ "docs": "Search and read the Polymarket documentation",
42
+ "account": "Your CLOB orders, trades, balances and relayer transactions",
43
+ "perps-account": "Your Perps balances, orders, fills and history",
44
+ "trading": "Place and cancel prediction market orders",
45
+ "wallet": "Approvals, split, merge and redeem through the Relayer",
46
+ "perps-trading": "Perps orders, leverage, margin, deposits and withdrawals",
47
+ "sports": "Sports metadata, teams, results and live scores",
48
+ "rewards": "Liquidity rewards, rebates and order scoring",
49
+ "streams": "Short WebSocket captures of books, prices and Perps markets",
50
+ "bridge": "Cross-chain deposits and withdrawals",
51
+ "combos": "Multi-leg Combo quotes and collateral return",
52
+ "builder": "Builder program boards, trades, keys and fee approvals",
53
+ "perps-extras": "Perps leaderboard, competitions, share cards and BLP",
54
+ }
55
+ DEFAULT_TOOLSETS = frozenset(
56
+ {
57
+ "discovery",
58
+ "market-data",
59
+ "analytics",
60
+ "perps-market",
61
+ "system",
62
+ "docs",
63
+ "account",
64
+ "perps-account",
65
+ "trading",
66
+ "wallet",
67
+ "perps-trading",
68
+ }
69
+ )
70
+ _META = {
71
+ "auto": DEFAULT_TOOLSETS,
72
+ "all": frozenset(TOOLSETS),
73
+ "perps": frozenset(name for name in TOOLSETS if name.startswith("perps")),
74
+ "predictions": frozenset(name for name in TOOLSETS if not name.startswith("perps")) - {"docs"},
75
+ }
76
+
77
+
78
+ def parse_toolsets(spec: str) -> frozenset[str]:
79
+ """`auto`, `all`, `predictions`, `perps`, names, and `+name` / `-name` adjustments."""
80
+ selected: set[str] = set()
81
+ tokens = [token.strip() for token in spec.split(",") if token.strip()] or ["auto"]
82
+ if all(token[0] in "+-" for token in tokens):
83
+ tokens.insert(0, "auto")
84
+ for token in tokens:
85
+ sign, name = (token[0], token[1:]) if token[0] in "+-" else ("+", token)
86
+ names = _META.get(name) or ({name} if name in TOOLSETS else None)
87
+ if names is None:
88
+ known = ", ".join([*_META, *TOOLSETS])
89
+ raise ConfigError(f"Unknown toolset {name!r} in POLYMARKET_TOOLSETS. Known: {known}.")
90
+ if sign == "+":
91
+ selected |= names
92
+ else:
93
+ selected -= names
94
+ return frozenset(selected)
95
+
96
+
97
+ @dataclass(frozen=True)
98
+ class Capabilities:
99
+ toolsets: frozenset[str]
100
+ have: frozenset[str]
101
+ gates: frozenset[str]
102
+ notes: tuple[str, ...] = field(default=())
103
+
104
+ @staticmethod
105
+ def _detect_signer(
106
+ settings: Settings, identity: Identity, have: set[str], notes: list[str]
107
+ ) -> None:
108
+ if identity.signer_address is not None and identity.wallet_address is None:
109
+ notes.append("POLYMARKET_WALLET_ADDRESS is needed before anything can be signed.")
110
+ if identity.signer_address is not None and settings.signer_role == "owner":
111
+ have.add("perps_owner")
112
+ if identity.signer_address is None or identity.wallet_address is None:
113
+ return
114
+ try:
115
+ _ = identity.wallet_kind
116
+ except ConfigError as exc:
117
+ notes.append(exc.for_agent())
118
+ return
119
+ have.add("signer")
120
+ if settings.signer_role == "owner":
121
+ have.add("owner_signer")
122
+
123
+ @staticmethod
124
+ def _detect_gates(settings: Settings) -> frozenset[str]:
125
+ gates: set[str] = set()
126
+ if settings.allow_cancel or settings.allow_trading:
127
+ gates.add("cancel")
128
+ if settings.allow_trading:
129
+ gates.add("trading")
130
+ if settings.allow_transfers:
131
+ gates.add("transfers")
132
+ return frozenset(gates)
133
+
134
+ @classmethod
135
+ def detect(cls, settings: Settings, identity: Identity) -> "Capabilities":
136
+ have: set[str] = set()
137
+ notes: list[str] = []
138
+ try:
139
+ if identity.clob_credentials() is not None:
140
+ have.add("clob_l2")
141
+ except ConfigError as exc:
142
+ notes.append(exc.message)
143
+ cls._detect_signer(settings, identity, have, notes)
144
+ if identity.relayer_key() is not None:
145
+ have.add("relayer_key")
146
+ session = identity.perps_session()
147
+ if session is not None:
148
+ have.add("perps_session")
149
+ if session.can_sign and signing_available():
150
+ have.add("perps_signer")
151
+ notes.extend(identity.notes)
152
+ return cls(
153
+ toolsets=parse_toolsets(settings.toolsets),
154
+ have=frozenset(have),
155
+ gates=cls._detect_gates(settings),
156
+ notes=tuple(dict.fromkeys(notes)),
157
+ )
158
+
159
+
160
+ def visible(
161
+ toolset: str, requires: tuple[str, ...], gate: str | None, caps: Capabilities
162
+ ) -> tuple[bool, str]:
163
+ """Whether a tool is exposed, and if not, the step that would expose it."""
164
+ if toolset not in caps.toolsets:
165
+ return False, f"add `{toolset}` to POLYMARKET_TOOLSETS (e.g. `auto,+{toolset}`)"
166
+ if gate is not None and gate not in caps.gates:
167
+ return False, f"set {GATES[gate]}"
168
+ missing = [name for name in requires if name not in caps.have]
169
+ if missing:
170
+ return False, "needs " + "; ".join(REQUIREMENTS[name] for name in missing)
171
+ return True, ""
@@ -0,0 +1,128 @@
1
+ import argparse
2
+ import asyncio
3
+ import json
4
+ import sys
5
+
6
+ import uvicorn
7
+ from pydantic import ValidationError
8
+
9
+ from mcp_server_polymarket import __version__, auth_flow
10
+ from mcp_server_polymarket.config import Settings
11
+ from mcp_server_polymarket.errors import PolymarketError
12
+ from mcp_server_polymarket.http_app import build_http_app
13
+ from mcp_server_polymarket.logging_setup import configure_logging
14
+ from mcp_server_polymarket.ops import Runtime, enabled_operations, hidden_operations
15
+ from mcp_server_polymarket.ops.registry import Call
16
+ from mcp_server_polymarket.ops.system import auth_status
17
+ from mcp_server_polymarket.server import create_server, detect_capabilities
18
+
19
+
20
+ def _parser() -> argparse.ArgumentParser:
21
+ parser = argparse.ArgumentParser(
22
+ prog="mcp-server-polymarket", description="MCP server for the Polymarket API (unofficial)."
23
+ )
24
+ parser.add_argument("--version", action="version", version=__version__)
25
+ commands = parser.add_subparsers(dest="command")
26
+
27
+ serve = commands.add_parser("serve", help="run the MCP server (default)")
28
+ serve.add_argument("--transport", choices=["stdio", "streamable-http"], default="stdio")
29
+ serve.add_argument("--host", default="127.0.0.1")
30
+ serve.add_argument("--port", type=int, default=8000)
31
+
32
+ auth = commands.add_parser("auth", help="create and store API credentials")
33
+ target = auth.add_mutually_exclusive_group()
34
+ target.add_argument("--perps", action="store_true", help="create a Perps trading session")
35
+ target.add_argument(
36
+ "--session-key",
37
+ metavar="ADDRESS",
38
+ help="authorise a session key on the Deposit Wallet (needs the owner's key)",
39
+ )
40
+ target.add_argument(
41
+ "--revoke-session-key", metavar="ADDRESS", help="revoke a Deposit Wallet session key"
42
+ )
43
+ target.add_argument(
44
+ "--builder-key", action="store_true", help="create a builder API key (needs CLOB auth)"
45
+ )
46
+ auth.add_argument("--read-only", action="store_true", help="Perps: a key that cannot trade")
47
+ auth.add_argument("--days", type=int, default=7, help="Perps: session lifetime in days")
48
+ auth.add_argument("--yes", action="store_true", help="do not ask for confirmation")
49
+
50
+ logout = commands.add_parser("logout", help="forget or revoke stored credentials")
51
+ logout.add_argument("--perps", action="store_true", help="revoke and forget the Perps session")
52
+ logout.add_argument(
53
+ "--revoke", action="store_true", help="also delete the CLOB API key at Polymarket"
54
+ )
55
+ logout.add_argument(
56
+ "--builder-key", action="store_true", help="revoke the builder API key at Polymarket"
57
+ )
58
+
59
+ commands.add_parser("status", help="show credentials, gates and hidden tools")
60
+ commands.add_parser("tools", help="list the tools this configuration exposes")
61
+ return parser
62
+
63
+
64
+ def _serve(args: argparse.Namespace, settings: Settings) -> int:
65
+ server = create_server(settings)
66
+ if args.transport == "stdio":
67
+ server.run()
68
+ return 0
69
+ app = build_http_app(server, settings, host=args.host)
70
+ uvicorn.run(app, host=args.host, port=args.port, log_config=None)
71
+ return 0
72
+
73
+
74
+ def _tools(settings: Settings) -> int:
75
+ caps = detect_capabilities(settings)
76
+ operations = enabled_operations(caps)
77
+ width = max((len(op.name) for op in operations), default=10)
78
+ for op in operations:
79
+ flag = " (experimental)" if op.experimental else ""
80
+ print(f"{op.name:<{width}} [{op.toolset}] {op.title}{flag}")
81
+ print(f"\n{len(operations)} tools.")
82
+ hidden: dict[str, list[str]] = {}
83
+ for op, reason in hidden_operations(caps):
84
+ hidden.setdefault(reason, []).append(op.name)
85
+ if hidden:
86
+ print("\nHidden:")
87
+ for reason, names in hidden.items():
88
+ print(f"- {len(names)} tools: {reason}")
89
+ return 0
90
+
91
+
92
+ async def _status(settings: Settings) -> int:
93
+ runtime = Runtime.create(settings)
94
+ try:
95
+ status = await auth_status(Call(runtime=runtime))
96
+ finally:
97
+ await runtime.aclose()
98
+ print(json.dumps(status.model_dump(mode="json"), indent=2))
99
+ return 0
100
+
101
+
102
+ def main(argv: list[str] | None = None) -> int:
103
+ args = _parser().parse_args(argv)
104
+ try:
105
+ settings = Settings()
106
+ except ValidationError as exc:
107
+ # Only names and reasons: the input values could be secrets.
108
+ for error in exc.errors():
109
+ name = "_".join(str(part) for part in error["loc"]).upper()
110
+ print(f"Invalid POLYMARKET_{name}: {error['msg']}", file=sys.stderr)
111
+ return 2
112
+ configure_logging(settings.log_level)
113
+ if args.command is None:
114
+ args = _parser().parse_args(["serve"])
115
+ try:
116
+ if args.command == "serve":
117
+ return _serve(args, settings)
118
+ if args.command == "status":
119
+ return asyncio.run(_status(settings))
120
+ if args.command in ("auth", "logout"):
121
+ handler = auth_flow.auth if args.command == "auth" else auth_flow.logout
122
+ return asyncio.run(handler(args, settings))
123
+ return _tools(settings)
124
+ except PolymarketError as exc:
125
+ print(exc.for_agent(), file=sys.stderr)
126
+ return 1
127
+ except (KeyboardInterrupt, EOFError):
128
+ return 130
File without changes
@@ -0,0 +1,62 @@
1
+ """Request authentication headers. Only the standard library: HMAC needs no signing extra."""
2
+
3
+ import base64
4
+ import hashlib
5
+ import hmac
6
+ from dataclasses import dataclass, field
7
+
8
+
9
+ def _decode_secret(secret: str) -> bytes:
10
+ # Polymarket issues URL-safe base64 secrets, sometimes without padding.
11
+ padded = secret + "=" * (-len(secret) % 4)
12
+ return base64.urlsafe_b64decode(padded.replace("+", "-").replace("/", "_"))
13
+
14
+
15
+ def hmac_signature(secret: str, timestamp: int, method: str, path: str, body: bytes | None) -> str:
16
+ """URL-safe base64 HMAC-SHA256 over timestamp + METHOD + path + body.
17
+
18
+ The path excludes the query string, and the body is the exact bytes sent.
19
+ """
20
+ message = f"{timestamp}{method.upper()}{path}".encode()
21
+ if body:
22
+ message += body
23
+ digest = hmac.new(_decode_secret(secret), message, hashlib.sha256).digest()
24
+ return base64.urlsafe_b64encode(digest).decode()
25
+
26
+
27
+ @dataclass(frozen=True)
28
+ class HmacKey:
29
+ api_key: str
30
+ secret: str = field(repr=False)
31
+ passphrase: str = field(repr=False)
32
+
33
+
34
+ def clob_l2_headers(
35
+ key: HmacKey, address: str, timestamp: int, method: str, path: str, body: bytes | None
36
+ ) -> dict[str, str]:
37
+ return {
38
+ "POLY_ADDRESS": address,
39
+ "POLY_SIGNATURE": hmac_signature(key.secret, timestamp, method, path, body),
40
+ "POLY_TIMESTAMP": str(timestamp),
41
+ "POLY_API_KEY": key.api_key,
42
+ "POLY_PASSPHRASE": key.passphrase,
43
+ }
44
+
45
+
46
+ def builder_headers(
47
+ key: HmacKey, timestamp: int, method: str, path: str, body: bytes | None
48
+ ) -> dict[str, str]:
49
+ return {
50
+ "POLY_BUILDER_API_KEY": key.api_key,
51
+ "POLY_BUILDER_TIMESTAMP": str(timestamp),
52
+ "POLY_BUILDER_PASSPHRASE": key.passphrase,
53
+ "POLY_BUILDER_SIGNATURE": hmac_signature(key.secret, timestamp, method, path, body),
54
+ }
55
+
56
+
57
+ def relayer_headers(api_key: str, address: str) -> dict[str, str]:
58
+ return {"RELAYER_API_KEY": api_key, "RELAYER_API_KEY_ADDRESS": address}
59
+
60
+
61
+ def perps_headers(proxy: str, secret: str) -> dict[str, str]:
62
+ return {"POLYMARKET-PROXY": proxy, "POLYMARKET-SECRET": secret}