{
  "markdown": "# cypher-mcp\n\n**Monetized graph answers over Bitcoin Lightning.** A Tollbooth-DPYC Operator\nthat sells *priced answers* from a graph — operator-authored, parameterized,\nnamed Cypher query templates — not raw database access.\n\nThe OSS Neo4j MCP servers are a free pipe to a database the operator\nseparately expenses (Neo4j invoice) and separately bills for (Stripe stack).\ncypher-mcp collapses infrastructure cost, application billing, and access\ncontrol into one metered MCP surface: the operator stops selling seats and\nstarts selling answers, settled in sats, with no Stripe stack and no Neo4j\ninvoice passed to the customer.\n\nLive at `https://cypher-mcp.fastmcp.app/mcp`.\n\n## How it works\n\nTwo planes, cleanly separated:\n\n- **Settlement / identity plane** — Neon + Nostr + Tollbooth, shared with\n  every other DPYC operator. It never knows a graph exists.\n- **Value-delivery plane** — Bolt → Neo4j, sealed *inside the tool handlers*\n  (`graph.py`), opened and torn down per request (no pool). The backing store\n  is an implementation detail invisible to patrons, so it can be swapped\n  without changing the MCP surface.\n\nThree conceptual layers:\n\n| Layer | Where | What |\n|---|---|---|\n| **L1 — primitive** | code (shipped once) | `execute_query_by_key(key, params)` + catalog CRUD |\n| **L2 — catalog** | Neon `query_catalog` | `key → vetted Cypher template + param schema` (*what's possible*) |\n| **L3 — pricing** | Tollbooth pricing model | *what's sold, named, priced* |\n\n> **Status: live, with named tools.** L1 + L2 are shipped and serving real,\n> billed answers — an operator adopted by an Authority, AuraDB-backed, with\n> refund-on-raise verified end to end. **Named tools are now live (L3 tool\n> synthesis):** an operator can `publish_tool(key)` to project a query as a\n> first-class, typed tool (e.g. `cypher_find_airline_flights(from_city,\n> to_city)`), priced individually in Pricing Studio. Per-key parametric *pricing\n> formulas* remain a later step — see [CHANGELOG.md](CHANGELOG.md).\n\n## Tools\n\n**Patron (priced):**\n\n- `cypher_execute_query_by_key(key, params)` — run a published query. You\n  supply only parameters; the operator owns the query text, and parameters\n  bind as Cypher `$params` (never string-interpolated). You're charged only\n  for a delivered answer — an unknown key, invalid parameters, or a failed\n  query rolls back the debit (refund-on-raise).\n\nPlus the standard DPYC surface from the wheel: `cypher_check_balance`,\n`cypher_check_price`, `cypher_purchase_credits`, Secure Courier, npub proof,\nOracle delegation, account statements, constraint-based dynamic pricing, etc.\n\n**Operator-only (restricted, unpriced) — the authoring plane:**\n\n- `cypher_create_query` / `cypher_update_query` / `cypher_get_query` /\n  `cypher_list_queries` / `cypher_delete_query`\n- `cypher_publish_tool(key)` / `cypher_unpublish_tool(key)` — project a query as\n  a first-class, typed named tool (or retire it). See *Named tools* below.\n\nRaw Cypher never reaches patrons — only named, parameterized templates.\n\n### Authoring in Neo4j's own UI — no second editor to learn\n\nA DB-analyst refines templates in Neo4j Browser, not in a bespoke tool.\n`cypher_get_query(key)` returns the template **plus an `edit_url`** — a deep\nlink into the hosted Neo4j Browser (`browser.neo4j.io`) that pre-targets the\noperator's AuraDB and loads the statement **in edit mode** (`cmd=edit`).\nRefine it with autocomplete, run-to-test, visualization, and `PROFILE`; then\nsave it back with `cypher_update_query`. The template is just a string flowing\nover MCP — no files, no desktop, no exported bundles. The link carries the\nDBMS URI but never the password, and `get_query` is operator-only, so neither\never reaches a patron.\n\n### Named tools — publish a query as its own tool\n\n`cypher_publish_tool(key)` projects a catalog query as a first-class MCP tool\nnamed `cypher_<key>` whose flat, typed parameters come from the query's schema —\ne.g. `cypher_find_airline_flights(from_city, to_city)`. An agent then calls it by\nname with typed params instead of `execute_query_by_key(key, params)`. Internally\nevery named tool funnels through the **same shared executor** (look the stored\nCypher up by key → parameter-bind → run), so there is one code path and the same\nrefund-on-raise guarantee. A published tool registers **unpriced** — it appears in\nPricing Studio like any new tool; set its price there (calls return \"not priced yet\n(TBD)\" until you do). `cypher_unpublish_tool(key)` retires the tool (the query\nitself stays, still runnable by key). Published tools survive restarts\n(re-materialized from the catalog); reconnect to observe tool-list changes.\n\nThe synthesis machinery is a generic `tollbooth-dpyc` primitive\n(`register_dynamic_tool`) — named Cypher queries are one realization; the same\nprimitive can back a synthesized tool with a REST call, SQL, or a stored prompt.\n\n## Onboarding (operator)\n\n1. **Request adoption** from an Authority (the deferred courtship —\n   `request_adoption`) or be registered directly. Either way the Authority\n   provisions an isolated Neon tenant automatically.\n2. Deliver operator secrets via Secure Courier\n   (`cypher_request_credential_channel`, service `cypher-operator`):\n   - `neo4j_uri`, `neo4j_user`, `neo4j_password` — the graph store\n     (e.g. a Neo4j AuraDB instance)\n   - `btcpay_host`, `btcpay_api_key`, `btcpay_store_id` — Lightning\n3. Author your catalog with `cypher_create_query`; patrons then execute by key.\n\n## Develop\n\n```bash\npip install -e \".[dev]\"\npytest -v\npython -m cypher_mcp.server   # needs TOLLBOOTH_NOSTR_OPERATOR_NSEC\n```\n\nDeployed on Prefect Horizon (FastMCP runtime); see `.fastmcp.yaml`. The only\nenv var required to boot is `TOLLBOOTH_NOSTR_OPERATOR_NSEC` — every other\nsecret arrives via Secure Courier.\n\n---\n\n## DPYC Ecosystem\n\n| Repo | Role |\n|------|------|\n| [tollbooth-dpyc](https://github.com/lonniev/tollbooth-dpyc) | Python SDK — vault, auth, pricing, payments, Nostr identity |\n| [dpyc-community](https://github.com/lonniev/dpyc-community) | Governance registry, membership, advisories, threat model |\n| [dpyc-oracle](https://github.com/lonniev/dpyc-oracle) | Community concierge — free onboarding help and membership lookup |\n| [tollbooth-authority](https://github.com/lonniev/tollbooth-authority) | Certification backbone — Schnorr-signed purchase order certificates |\n| [tollbooth-sample](https://github.com/lonniev/tollbooth-sample) | Sample Operator — canonical template for new MCP services |\n| [tollbooth-pricing-studio](https://github.com/lonniev/tollbooth-pricing-studio) | iOS app — visual pricing-model editor and operator console |\n| [schwab-mcp](https://github.com/lonniev/schwab-mcp) | Charles Schwab brokerage data (operational example) |\n| [thebrain-mcp](https://github.com/lonniev/thebrain-mcp) | TheBrain personal knowledge graph (operational example) |\n| [excalibur-mcp](https://github.com/lonniev/excalibur-mcp) | X/Twitter posting (operational example) |\n| [taxsort-mcp](https://github.com/lonniev/taxsort-mcp) | Tax classification + Cloudflare Pages UI (operational example) |\n| [tollbooth-oauth2-collector](https://github.com/lonniev/tollbooth-oauth2-collector) | OAuth2 callback handler — shared advocate service |\n| [stablecoin.myshopify.com](https://stablecoin.myshopify.com) | DPYC merch and Austrian economics |\n\n## Prior Art & Attribution\n\nThe methods, algorithms, and implementations contained in this repository may\nrepresent original work by Lonnie VanZandt, first published on June 15, 2026.\nThis public disclosure establishes prior art under U.S. patent law\n(35 U.S.C. 102).\n\nAll use, reproduction, or derivative work must comply with the Apache License\n2.0 included in this repository and must provide proper attribution to the\noriginal author per the [NOTICE](NOTICE) file.\n\n### How to Attribute\n\nIf you use or build upon this work, please include the following in your\ndocumentation or source:\n\n    Based on original work by Lonnie VanZandt and Claude.ai\n    Originally published: June 15, 2026\n    Source: https://github.com/lonniev/cypher-mcp\n    Licensed under Apache License 2.0\n\nVisit the technologist's virtual cafe for Bitcoin advocates and coffee\naficionados at [stablecoin.myshopify.com](https://stablecoin.myshopify.com).\n\n### Patent Notice\n\nThe author reserves all rights to seek patent protection for the novel methods\nand systems described herein. Public disclosure of this work establishes a\npriority date of June 15, 2026. Under the America Invents Act, the author\nretains a one-year grace period from the date of first public disclosure to\nfile patent applications.\n\n**Note to potential filers:** This public repository and its full Git history\nserve as evidence of prior art. Any patent application covering substantially\nsimilar methods filed after the publication date of this repository may be\nsubject to invalidation under 35 U.S.C. 102(a).\n\n## Further Reading\n\n[The Phantom Tollbooth on the Lightning Turnpike](https://stablecoin.myshopify.com/blogs/our-value/the-phantom-tollbooth-on-the-lightning-turnpike)\n— the full story of how we're monetizing the monetization of AI APIs, and\nthen fading to the background.\n\n## Software Factory intent vocabulary (DPYC agents)\n\ncypher-mcp is the graph substrate for the DPYC Software Factory: its agents (Porter =\nService Desk, Journeyman = Engineering) read and write an institutional-memory graph here\n**without ever holding a raw Cypher tool**. They call a fixed vocabulary of\noperator-authored, parameterized templates — currently 43 (25 *write*, 18 *read*) —\npublished as typed `cypher_<key>` tools.\n\n- **Write templates** capture the memory: `record_triage`, `note_rejection`,\n  `route_rejection` (anti-ping-pong: bounce a rejection back to its origin), `record_scope`,\n  `link_root_cause`, `link_pr`, `assert_rationale`, `bind_rationale_to_symbol`,\n  `anchor_symbol` (post-edit grep-scoping anchor), `upsert_capability`, `assert_invariant`,\n  `upsert_patent_element`, `register_service`, and more.\n- **Read templates** are the intention-service *forward map* — the RAG surface that resolves\n  \"which service handles X / why does this capability exist\" in one query instead of a\n  twelve-repo grep: `which_service_handles`, `explain_capability`, `what_realizes_capability`,\n  `capability_patents`, `context_pack` (the flagship grep-scoping bundle), `list_capabilities`,\n  `list_invariants`, `list_patent_elements`, `routing_history`, `recent_activity`,\n  `factory_resolution_stats`, and their provenance readers.\n\n`assert_rationale` hard-codes `provenance:'llm-inferred-unverified'` as a Cypher literal, so\nan agent key can never claim authoritative provenance.\n\n**Start unlimited, limit later.** Seeding just authors + publishes the tools; they then\nappear in **Pricing Studio** unpriced. Price them and any funded patron can call — the two\nagents just purchase api_sats like any patron. When you want to restrict calls to the two,\nadd — in a Pricing Studio session — a `json_expression` allow-list on `patron.npub` per tool\n(Constraint Engine, not a bespoke ACL): listed npub allowed, everyone else denied by default,\nruntime-mutable with no deploy. Containment is also by **balance** — fund the Porter thin and\nthe Journeyman thicker; a drained agent stops writing the graph but still triages on GitHub.\n\n**Seeding (operator, idempotent).** `scripts/seed_factory_vocabulary.py` authors + publishes\nthe vocabulary. `--dry-run` needs no server or nsec and also prints the exact allow-list to\nreplicate in Pricing Studio when you limit access:\n\n```bash\npython scripts/seed_factory_vocabulary.py --dry-run \\\n    --porter-npub npub1ymg... --journeyman-npub npub1m5q...\n```\n\nApply against the live operator (operator nsec used transiently to sign one-shot kind-27235\nproofs — never logged or written to disk). Add `--gate` (with both npubs) to also apply the\nper-npub allow-list programmatically instead of in Pricing Studio:\n\n```bash\npython scripts/seed_factory_vocabulary.py \\\n    --url https://cypher-mcp.fastmcp.app/mcp --operator-npub npub1fuhq0...\n```\n\nThe vocabulary itself lives in `scripts/factory_vocabulary.py` (data, no I/O) and is covered\nby `tests/test_factory_vocabulary.py`. Pipeline wiring (agents signing and calling these\ntools), NIP-05 publication, and funding are downstream of this substrate.\n\n## Trademarks\n\nDPYC&trade;, Tollbooth DPYC&trade;, and Don't Pester Your Customer&trade; are\ntrademarks of Lonnie VanZandt. See\n[TRADEMARKS.md](https://github.com/lonniev/dpyc-community/blob/main/TRADEMARKS.md)\nin the dpyc-community repository for usage guidelines.\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE) for details.\n\n---\n\n*Because in the end, the tollbooth was never the destination. It was always\njust the beginning of the journey.*\n",
  "bytes": 12772,
  "sha": "f75d537d0ca192ad8b282ff9c16d4c99054470b4bd65f0285e3caf17a278d90f",
  "repo_slug": "lonniev/cypher-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_lonniev_cypher_mcp_a47b1e24/readme"
}