Making GovTool ready for the AI era

[sireto-sandip]

Making GovTool ready for the AI era

Governance tooling has two audiences now: people, and the agents people delegate to. GovTool is currently built only for the first. This issue proposes the work needed to serve both — so that contributing to GovTool with an AI coding agent is straightforward, and so that governance data on Cardano is legible to agents acting on a user's behalf.

This is a discussion issue, not a decided plan. Push back on any of it.

1. Make the codebase ready for agentic contribution

The goal: someone points Claude Code, Codex, or a similar agent at this repository, and it can orient itself, make a change, and verify that change without a human babysitting every step.

• Agent context files. CLAUDE.md and AGENTS.md at the repo root, plus per-package files where the conventions differ. These need to cover the things that take a newcomer a day to work out: that backend query logic lives in .sql files rather than Haskell, that reads flow services/requests → hooks/queries → component, that the discussion and outcomes pillars are external npm packages and not fixable here.
• A local stack an agent can actually run. This is the single biggest blocker. Today, running GovTool means running a Cardano node and a cardano-db-sync instance. No agent is going to do that, and most humans would rather not either. We want one command, a seeded fixture database, and no chain dependency for the majority of work.
• A test suite that runs locally and fast. The Playwright suites currently run against deployed environments, which means an agent cannot use them to check its own work. Tests an agent can run in a loop are what make agentic contribution safe rather than merely possible.
• An explicit definition of done. The CI gates (npm run test, npm run lint, npm run tsc) should be stated somewhere an agent will read them, so it verifies before opening a PR rather than after review.
• Issues written to be picked up cold. Our issue templates were written for humans who already have context. An agent needs the affected package, reproduction steps, and the acceptance criteria stated explicitly. This mostly costs discipline, not engineering.

2. Refactor the API to be properly RESTful

The current API grew organically and shows it. From the Servant definition:

GET /drep/list
GET /drep/get-voting-power/:drepId
GET /drep/getVotes/:drepId <- camelCase, unlike its neighbours
GET /drep/info/:drepId
GET /ada-holder/get-current-delegation/:stakeKey
GET /proposal/list
GET /proposal/get/:proposalId
GET /account/:stakeKey <- the one that got it right
GET /throw500 <- a test endpoint, publicly routable

Verbs in paths, inconsistent casing, and a deliberate 500-thrower on the public surface. For a human reading docs this is friction; for an agent inferring how to call the next endpoint, it is a wall.

Proposed: resource-oriented paths (/dreps, /dreps/{id}, /dreps/{id}/votes, /proposals, /proposals/{id}), consistent casing, consistent pagination and filtering, real status codes, and stable identifiers throughout (CIP-129 where applicable). The backend already emits an OpenAPI 3 document at /swagger.json — worth treating that spec as a first-class artifact: publish it, version it, generate the typed frontend client and test fixtures from it rather than hand-writing them.

This lines up naturally with the TypeScript backend rewrite.

3. Expose an MCP interface

An MCP server over governance data would let any MCP-capable assistant answer questions like "what governance actions are open right now", "how has this DRep voted", "what changed in the treasury proposal I delegated against" — without scraping the UI or reimplementing our API client.

Two distinct surfaces, worth keeping separate:

• A public governance-data MCP server — read-only, for anyone building agent workflows on Cardano governance. This is the one with real ecosystem value, and it is mostly a thin layer over a clean REST API, which is why item 2 comes first.
• A contributor-facing MCP server — repo, test environment, and fixture access for people working on GovTool itself.

Deliberately out of scope for now: anything that signs or submits a transaction. Voting is consequential, and an agent should be able to prepare and explain a vote, never cast one. If we ever revisit that, it needs its own discussion.

4. Make governance data legible to machines

• Governance action metadata already follows CIP-100/108 JSON-LD, which is a genuine head start. We should make sure what we serve preserves that structure rather than flattening it.
• Stable, resolvable identifiers for every entity an agent might cite — proposals, DReps, votes — so an agent's answer can be checked against a URL.
• An llms.txt and structured metadata on gov.tools, so assistants that reach the site by search rather than by API get accurate information about what GovTool is and where the data lives.

5. Guardrails, and one thing worth being careful about

• Exposing more surface raises the stakes on the surface we already have. An MCP server and a public API make those more attractive, not less. Auth, rate limiting, and abuse controls need to land before or alongside the MCP work, not after it.
• A policy for AI-assisted contributions. We welcome them. We also want to be clear about what we expect: that the contributor understands and can defend the change, that generated code gets the same review as any other, and that security-sensitive areas get a human pass. Worth writing down before volume picks up rather than after.
• No automated summarisation of governance actions in the product. People vote on these. A confident, subtly wrong summary of a treasury proposal is worse than no summary. If we ever ship anything in this direction it needs human review in the loop and a visible provenance trail — and it should be a separate, explicit decision.

Sequencing

Rough order, since much of this depends on what comes before it:

1. Local dev environment and a locally runnable test suite — unblocks everything else, agentic or not.
2. Agent context files and issue hygiene — cheap, immediate benefit.
3. REST refactor, alongside the TypeScript backend rewrite.
4. OpenAPI spec as a published artifact, with generated clients.
5. Public MCP server, once there is a clean API and auth story under it.
6. Data legibility and llms.txt.

What we would like from you

• Which of these matter to you, and which are solving a problem you do not have?
• If you are building agent tooling on Cardano governance already: what would you want from an MCP server, and what does our current API make unnecessarily hard?
• Is anyone opposed to the REST refactor breaking existing API consumers? We would need a deprecation window and would like to know who to talk to.

Disclosure: The issue description is AI generated based on (my) personal/human draft for better clarity of text and coherence.