clause-mcp 0.1.0__tar.gz

clause_mcp-0.1.0/LICENSE

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

clause_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: clause-mcp
+Version: 0.1.0
+Summary: MCP server for prediction markets: are these two contracts the same bet, and how much size will this market actually take?
+Author: Clause
+License-Expression: MIT
+Keywords: mcp,model-context-protocol,prediction-markets,polymarket,kalshi,order-book,liquidity,market-microstructure
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.28
+Requires-Dist: mcp>=2.0
+Provides-Extra: api
+Requires-Dist: fastapi>=0.115; extra == "api"
+Requires-Dist: uvicorn[standard]>=0.32; extra == "api"
+Provides-Extra: chain
+Requires-Dist: eth-abi>=5.0; extra == "chain"
+Requires-Dist: eth-hash[pycryptodome]>=0.7; extra == "chain"
+Requires-Dist: websockets>=15; extra == "chain"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2; extra == "postgres"
+Provides-Extra: analysis
+Requires-Dist: duckdb>=1.5; extra == "analysis"
+Requires-Dist: rapidfuzz>=3.14; extra == "analysis"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# clause-mcp
+
+**You are about to trade a spread between two contracts that resolve
+differently, and nothing you own will tell you.**
+
+Polymarket lists *"U.S. enacts AI safety bill before 2027?"*. Kalshi lists what
+reads as the same contract. Polymarket's resolves YES only on **restrictive
+provisions**. Kalshi's resolves YES on a federal framework *"regardless of
+whether those provisions mandate private-sector compliance or **promote
+voluntary guidelines**."*
+
+A voluntary standards act resolves one YES and the other NO. They are not the
+same bet at any price. Every arbitrage screen in existence shows them as one
+market at a spread, and a language model reading both rules texts will agree
+with the screen — because the divergence is not a difference between the two
+documents. It is **an explicit clause on one side matched by silence on the
+other**, and silence is the one thing a comparator has to be told not to read
+as agreement.
+
+This is an MCP server. It gives an agent the checks it cannot perform on its
+own.
+
+---
+
+## The second failure: the book that isn't there
+
+A market on a major venue reported **$65,883** of order-book depth. Within a
+sensible band of its own mid it held **$33**. It had traded **$122 in thirty
+days**. Putting $200,000 into it is 49,276 days of volume — **135 years**.
+
+A book is an offer. The tape is a fact. When they disagree, believe the tape.
+
+---
+
+## Install
+
+```bash
+pip install clause-mcp
+```
+
+### Claude Code
+
+```bash
+claude mcp add --scope user clause -- clause-mcp
+```
+
+`--scope user` matters: the default registers the server for one project
+directory only. **The tools appear in a new session**, not the one you ran the
+add from.
+
+### Claude Desktop, or any stdio client
+
+```json
+{
+  "mcpServers": {
+    "clause": { "command": "clause-mcp" }
+  }
+}
+```
+
+Streamable-HTTP instead of stdio: `clause-mcp --http --port 8848`.
+
+---
+
+## The eight tools
+
+| Tool | Answers | Needs |
+| --- | --- | --- |
+| `check_equivalence` | are these two contracts the same bet? | live venues |
+| `market_liquidity` | can this market absorb size — book *and* tape | live venues |
+| `preflight` | will this specific order work, with numbers | live venues |
+| `capacity` | how much fits inside 0.5¢ / 1¢ / 2¢ / 5¢ | live venues |
+| `resting_order` | rest or cross, and how long to fill | live venues |
+| `venue_conventions` | how each venue's API lies to you | nothing |
+| `find_markets` | identifiers the other tools need | an archive |
+| `identify_market` | which contract did the user mean, in plain words | an archive |
+
+**Six of the eight work the moment you install this.** They read the venues
+live and need no local data.
+
+The two search tools need a Clause archive — a hash-chained daily record of
+every open market's terms. This package does not ship one, and it will not
+pretend otherwise: with no archive, both tools **refuse**, name the state, and
+say in words that nothing was searched.
+
+```json
+{
+  "ok": false,
+  "error": "archive_unavailable",
+  "this_is_not_a_negative_result":
+    "Do NOT report this as 'no such market' or 'no results'. Nothing was
+     searched. The named market may exist and be trading; this install
+     simply has no corpus to look in."
+}
+```
+
+That refusal is the point of the package rather than a limitation of it. The
+alternative — falling back to a live search — is what the tool exists to
+avoid: Polymarket's list API caps pages at 100 rows and rejects offsets past
+~2,100, so a live search silently misses the quiet markets, which are exactly
+the ones whose liquidity most needs checking. Point `CLAUSE_DB` at an archive
+if you have one.
+
+---
+
+## Why the tool descriptions read the way they do
+
+They are written for the agent, not for a human browsing a catalogue. An agent
+does not know it has a problem, so each description leads with the failure it
+prevents rather than with what the tool returns. A tool called after the
+mistake has been made is a tool that did nothing.
+
+The verdicts are built the same way. `check_equivalence` returns two of them,
+because two different things can make two contracts different bets. `verdict`
+compares thresholds and settlement sources; it can reach `EQUIVALENT` when
+both are genuinely comparable. `criteria_verdict` compares the *provisions* —
+subject, jurisdiction, actor, action breadth, voluntary conduct, logical
+structure, carve-outs — and it **never returns a bare `EQUIVALENT`**:
+`LIKELY_EQUIVALENT` is its ceiling, with the clauses to read attached. That is
+the one that catches the AI bills above, and roughly half the board resolves
+on provisions rather than on numbers.
+
+An `unknown` on a material field returns `REVIEW_REQUIRED`, never a pass.
+`INSUFFICIENT_DATA` is a distinct verdict from `LIQUID` and must never render
+as one.
+
+---
+
+## `venue_conventions`
+
+Thirteen documented ways a venue API returns HTTP 200 while being wrong, each
+one found by losing time to it and each one pinned by a test. A sample:
+
+- Polymarket's `/book` returns **asks descending** — `asks[0]` is the worst price.
+- A **YES bid at 0.10 is a NO ask at 0.90**. One order, two books. Never add the ladders.
+- `data-api /trades` **ignores the `asset` parameter** and returns the full tape. A five-row sample "confirms" the filter works.
+- Trades are **newest-first**; a capped pull is recent history, so dividing by 30 days understates a busy market ~15×.
+- Kalshi's orderbook is under `orderbook_fp`, and **both sides are resting bids** — the NO ask is `1 − best YES bid`.
+- Limitless caps `limit` at 25 and **400s above it**, which reads as "0 markets found".
+
+The meta-lesson, and the reason the tools refuse the way they do: **a check
+that cannot run reads as a check that passed.**
+
+---
+
+## Honest status
+
+Version 0.1.0. The verdicts are conservative by construction and the refusals
+are deliberate, but this is early software with no user base behind it yet.
+It measures and records; **it does not recommend positions and it is not legal
+advice**. Order transmission is off.
+
+Requires Python 3.11+. Tested on 3.13.
+
+**Name collision:** an unrelated PyPI package called `clause` (a Chinese NLP
+SDK) also installs a top-level `clause` module. Installing both into one
+environment will produce a broken hybrid. Run this server with `uvx`, `pipx`,
+or its own virtualenv — which is how MCP servers are usually run anyway.
+
+MIT licensed.

clause_mcp-0.1.0/README.md

@@ -0,0 +1,160 @@
+# clause-mcp
+
+**You are about to trade a spread between two contracts that resolve
+differently, and nothing you own will tell you.**
+
+Polymarket lists *"U.S. enacts AI safety bill before 2027?"*. Kalshi lists what
+reads as the same contract. Polymarket's resolves YES only on **restrictive
+provisions**. Kalshi's resolves YES on a federal framework *"regardless of
+whether those provisions mandate private-sector compliance or **promote
+voluntary guidelines**."*
+
+A voluntary standards act resolves one YES and the other NO. They are not the
+same bet at any price. Every arbitrage screen in existence shows them as one
+market at a spread, and a language model reading both rules texts will agree
+with the screen — because the divergence is not a difference between the two
+documents. It is **an explicit clause on one side matched by silence on the
+other**, and silence is the one thing a comparator has to be told not to read
+as agreement.
+
+This is an MCP server. It gives an agent the checks it cannot perform on its
+own.
+
+---
+
+## The second failure: the book that isn't there
+
+A market on a major venue reported **$65,883** of order-book depth. Within a
+sensible band of its own mid it held **$33**. It had traded **$122 in thirty
+days**. Putting $200,000 into it is 49,276 days of volume — **135 years**.
+
+A book is an offer. The tape is a fact. When they disagree, believe the tape.
+
+---
+
+## Install
+
+```bash
+pip install clause-mcp
+```
+
+### Claude Code
+
+```bash
+claude mcp add --scope user clause -- clause-mcp
+```
+
+`--scope user` matters: the default registers the server for one project
+directory only. **The tools appear in a new session**, not the one you ran the
+add from.
+
+### Claude Desktop, or any stdio client
+
+```json
+{
+  "mcpServers": {
+    "clause": { "command": "clause-mcp" }
+  }
+}
+```
+
+Streamable-HTTP instead of stdio: `clause-mcp --http --port 8848`.
+
+---
+
+## The eight tools
+
+| Tool | Answers | Needs |
+| --- | --- | --- |
+| `check_equivalence` | are these two contracts the same bet? | live venues |
+| `market_liquidity` | can this market absorb size — book *and* tape | live venues |
+| `preflight` | will this specific order work, with numbers | live venues |
+| `capacity` | how much fits inside 0.5¢ / 1¢ / 2¢ / 5¢ | live venues |
+| `resting_order` | rest or cross, and how long to fill | live venues |
+| `venue_conventions` | how each venue's API lies to you | nothing |
+| `find_markets` | identifiers the other tools need | an archive |
+| `identify_market` | which contract did the user mean, in plain words | an archive |
+
+**Six of the eight work the moment you install this.** They read the venues
+live and need no local data.
+
+The two search tools need a Clause archive — a hash-chained daily record of
+every open market's terms. This package does not ship one, and it will not
+pretend otherwise: with no archive, both tools **refuse**, name the state, and
+say in words that nothing was searched.
+
+```json
+{
+  "ok": false,
+  "error": "archive_unavailable",
+  "this_is_not_a_negative_result":
+    "Do NOT report this as 'no such market' or 'no results'. Nothing was
+     searched. The named market may exist and be trading; this install
+     simply has no corpus to look in."
+}
+```
+
+That refusal is the point of the package rather than a limitation of it. The
+alternative — falling back to a live search — is what the tool exists to
+avoid: Polymarket's list API caps pages at 100 rows and rejects offsets past
+~2,100, so a live search silently misses the quiet markets, which are exactly
+the ones whose liquidity most needs checking. Point `CLAUSE_DB` at an archive
+if you have one.
+
+---
+
+## Why the tool descriptions read the way they do
+
+They are written for the agent, not for a human browsing a catalogue. An agent
+does not know it has a problem, so each description leads with the failure it
+prevents rather than with what the tool returns. A tool called after the
+mistake has been made is a tool that did nothing.
+
+The verdicts are built the same way. `check_equivalence` returns two of them,
+because two different things can make two contracts different bets. `verdict`
+compares thresholds and settlement sources; it can reach `EQUIVALENT` when
+both are genuinely comparable. `criteria_verdict` compares the *provisions* —
+subject, jurisdiction, actor, action breadth, voluntary conduct, logical
+structure, carve-outs — and it **never returns a bare `EQUIVALENT`**:
+`LIKELY_EQUIVALENT` is its ceiling, with the clauses to read attached. That is
+the one that catches the AI bills above, and roughly half the board resolves
+on provisions rather than on numbers.
+
+An `unknown` on a material field returns `REVIEW_REQUIRED`, never a pass.
+`INSUFFICIENT_DATA` is a distinct verdict from `LIQUID` and must never render
+as one.
+
+---
+
+## `venue_conventions`
+
+Thirteen documented ways a venue API returns HTTP 200 while being wrong, each
+one found by losing time to it and each one pinned by a test. A sample:
+
+- Polymarket's `/book` returns **asks descending** — `asks[0]` is the worst price.
+- A **YES bid at 0.10 is a NO ask at 0.90**. One order, two books. Never add the ladders.
+- `data-api /trades` **ignores the `asset` parameter** and returns the full tape. A five-row sample "confirms" the filter works.
+- Trades are **newest-first**; a capped pull is recent history, so dividing by 30 days understates a busy market ~15×.
+- Kalshi's orderbook is under `orderbook_fp`, and **both sides are resting bids** — the NO ask is `1 − best YES bid`.
+- Limitless caps `limit` at 25 and **400s above it**, which reads as "0 markets found".
+
+The meta-lesson, and the reason the tools refuse the way they do: **a check
+that cannot run reads as a check that passed.**
+
+---
+
+## Honest status
+
+Version 0.1.0. The verdicts are conservative by construction and the refusals
+are deliberate, but this is early software with no user base behind it yet.
+It measures and records; **it does not recommend positions and it is not legal
+advice**. Order transmission is off.
+
+Requires Python 3.11+. Tested on 3.13.
+
+**Name collision:** an unrelated PyPI package called `clause` (a Chinese NLP
+SDK) also installs a top-level `clause` module. Installing both into one
+environment will produce a broken hybrid. Run this server with `uvx`, `pipx`,
+or its own virtualenv — which is how MCP servers are usually run anyway.
+
+MIT licensed.

clause_mcp-0.1.0/clause/adapters/__init__.py

@@ -0,0 +1,13 @@
+"""Venue adapters.
+
+Importing this package registers every adapter. The registry is populated by
+`@REGISTRY.register` at class definition, so it only knows the venues whose
+modules something has imported -- which made `REGISTRY.storable()` return
+whatever the importer happened to touch. The cross-venue matcher asked it for
+the list of venues it may write, got a partial answer, and would have refused
+every pair while exiting 0.
+"""
+
+from clause.adapters import kalshi, limitless, polymarket, predictit  # noqa: F401
+
+__all__ = ["kalshi", "limitless", "polymarket", "predictit"]

clause_mcp-0.1.0/clause/adapters/base.py

@@ -0,0 +1,203 @@
+"""Venue adapter framework — one interface, twenty venues.
+
+The market went from two venues that mattered to twenty-plus in eighteen
+months, and it is still moving. An adapter has to be a day of work or the
+coverage that is supposed to be our moat becomes our bottleneck.
+
+What every adapter must declare, and why each one is enforced rather than
+documented:
+
+  `storage_permitted`   Limitless restricts data compilations, and any venue
+                        whose terms are unread defaults to False.
+                        A flag that lives in a comment gets ignored; this one
+                        is checked before any write. Kalshi was the original
+                        reason this exists and is no longer an example of it:
+                        written authorisation on 2026-09-07 lifted its
+                        Developer Agreement s3.1 restriction. The mechanism
+                        outlived the case that motivated it, which is the
+                        point of putting it in the type rather than a note.
+  `book_supported`      not every venue exposes depth, and capacity silently
+                        returning nothing is worse than an honest refusal.
+  `terms_field`         which field carries resolution criteria. The whole
+                        equivalence layer depends on finding it.
+
+**When a venue's terms of service cannot be verified, the default is
+restrictive.** That is the posture already taken with Limitless, and it is the
+one that keeps us able to sell to venues rather than being blocked by them.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Iterator, Literal
+
+from clause.execution.capacity import Book
+
+VenueStatus = Literal["live", "beta", "planned", "blocked"]
+
+
+@dataclass(frozen=True)
+class VenueMarket:
+    """A market as any venue describes it, normalised."""
+    venue: str
+    venue_market_id: str
+    title: str
+    body: str                       # resolution criteria as published
+    outcome_token_ids: tuple[str, ...] = ()
+    condition_id: str | None = None
+    slug: str | None = None
+    close_time: int | None = None
+    status: str = "open"
+    raw: dict = field(default_factory=dict, compare=False, repr=False)
+
+
+@dataclass(frozen=True)
+class VenueCapabilities:
+    """What an adapter can actually do. Absent capabilities are refused, not faked."""
+    markets: bool = True
+    terms: bool = True
+    book: bool = False
+    trades: bool = False
+    streaming: bool = False
+    order_construction: bool = False
+
+
+class VenueAdapter(ABC):
+    """Implement four methods and declare your permissions."""
+
+    venue: str = "unnamed"
+    display_name: str = "Unnamed"
+    status: VenueStatus = "planned"
+
+    # Hard gate, checked before persistence. Default deny.
+    storage_permitted: bool = False
+    tos_url: str | None = None
+    tos_verified_on: str | None = None
+    tos_note: str = "terms not verified — treated as restrictive"
+
+    capabilities: VenueCapabilities = VenueCapabilities()
+
+    @abstractmethod
+    def list_markets(self, max_markets: int = 1000) -> Iterator[VenueMarket]:
+        ...
+
+    def fetch_book(self, token_id: str) -> Book:
+        raise NotImplementedError(
+            f"{self.venue} does not expose order-book depth")
+
+    def close(self) -> None:
+        return None
+
+    # ---------- enforcement ----------
+
+    def assert_can_store(self) -> None:
+        """Raise rather than write when the terms do not permit it.
+
+        Called at the persistence boundary. A permission expressed only as a
+        comment is a permission that gets ignored during a refactor.
+        """
+        if not self.storage_permitted:
+            raise PermissionError(
+                f"{self.venue}: storage not permitted "
+                f"({self.tos_note}). Derived values only — raw content from "
+                f"this venue must not be persisted.")
+
+    def describe(self) -> dict:
+        return {
+            "venue": self.venue,
+            "display_name": self.display_name,
+            "status": self.status,
+            "storage_permitted": self.storage_permitted,
+            "tos": {"url": self.tos_url, "verified_on": self.tos_verified_on,
+                    "note": self.tos_note},
+            "capabilities": {
+                "markets": self.capabilities.markets,
+                "terms": self.capabilities.terms,
+                "book": self.capabilities.book,
+                "trades": self.capabilities.trades,
+                "streaming": self.capabilities.streaming,
+                "order_construction": self.capabilities.order_construction,
+            },
+        }
+
+
+class Registry:
+    """Every known venue, including the ones we deliberately do not ingest.
+
+    Blocked venues stay listed with their reason. A venue that silently
+    disappears from a registry looks like one nobody thought about; a venue
+    listed as blocked, with the clause that blocked it, is a decision.
+    """
+
+    def __init__(self) -> None:
+        self._adapters: dict[str, type[VenueAdapter]] = {}
+        self._blocked: dict[str, str] = {}
+
+    def register(self, adapter_cls: type[VenueAdapter]) -> type[VenueAdapter]:
+        self._adapters[adapter_cls.venue] = adapter_cls
+        return adapter_cls
+
+    def block(self, venue: str, reason: str) -> None:
+        self._blocked[venue] = reason
+
+    def get(self, venue: str) -> type[VenueAdapter]:
+        if venue in self._blocked:
+            raise KeyError(f"{venue} is blocked: {self._blocked[venue]}")
+        if venue not in self._adapters:
+            raise KeyError(f"no adapter registered for {venue!r}")
+        return self._adapters[venue]
+
+    def storable(self) -> list[str]:
+        return [v for v, a in self._adapters.items() if a.storage_permitted]
+
+    def with_books(self) -> list[str]:
+        return [v for v, a in self._adapters.items() if a.capabilities.book]
+
+    def describe_all(self) -> dict:
+        return {
+            "registered": [a().describe() for a in self._adapters.values()],
+            "blocked": [{"venue": v, "reason": r}
+                        for v, r in self._blocked.items()],
+            "counts": {
+                "registered": len(self._adapters),
+                "storable": len(self.storable()),
+                "with_books": len(self.with_books()),
+                "blocked": len(self._blocked),
+            },
+        }
+
+
+REGISTRY = Registry()
+
+# Recorded so the reasoning is not lost. Probed 2026-09-02.
+REGISTRY.block(
+    "myriad",
+    "api.myriad.markets answers 'Service Healthy' but exposes no documented "
+    "market path; the Polkamarkets backend rejected all eleven pagination "
+    "conventions tried. Blocked pending real documentation.")
+REGISTRY.block(
+    "coinbase",
+    "not a venue — Coinbase 'Predict' routes through Kalshi's matching engine.")
+REGISTRY.block(
+    "kraken", "announced, not live as of 2026-09-02.")
+REGISTRY.block(
+    "sporttrade",
+    "not trading: exited US sports betting 25 May 2026; CFTC DCM/DCO "
+    "application filed Feb 2026 and still pending as of 2026-09-09.")
+
+# Verified 2026-09-09 by reading the clause, not a summary of it. This is
+# the only venue found whose terms prohibit this product by description.
+REGISTRY.block(
+    "sx_bet",
+    "terms forbid content being \"merged with other data\" or any "
+    "activity intended to \"collect, store, reorganise or manipulate\" it, "
+    "and separately prohibit scraping their odds. Cross-venue merging is "
+    "precisely this product, so there is no permitted reading. "
+    "help.sx.bet/en/articles/3613372-terms-and-conditions")
+
+REGISTRY.block(
+    "metaculus",
+    "licence is limited, personal, non-exclusive and non-commercial, and "
+    "automated collection is barred except through their own API; they also "
+    "403 us outright. Verified 2026-09-09.")