tbd/README.md

tbd

A small Clojure HTTP API built on Ring (Jetty) and reitit, with a ClojureScript re-frame front end (ui/), Swagger UI docs, unit tests, dockerized integration tests, and joint line coverage.

Requirements

• Docker, for the integration tests and the script/docker-* tasks (all CI needs)
• For running tasks natively (optional): Clojure CLI (tools.deps) with JDK 21+, Node 20+ (22.22+ for the UI tests; with a JDK) for the UI build, and Babashka for script/coverage-report

Running

script/ui-build        # compile the UI (once, and after UI changes)
script/server [port]

The server listens on port 3000 by default; pass a port argument or set PORT to change it (the argument wins):

script/server 8080
PORT=8080 script/server

This is a thin wrapper around clojure -X:run, which also honors PORT. Then open http://localhost:3000 for the UI. Without script/ui-build the server still starts, but / shows a placeholder.

Or build and run the container:

docker build -t tbd .
docker run --rm -p 3000:3000 tbd

API

Method	Path	Description
GET	/	The UI: an HTML shell that loads the compiled ClojureScript from /js/main.js
GET	/api/ping	Health check, returns pong
GET	/api/add?x=2&y=3	Adds two numbers: {:result 5} (EDN by default, see Formats) (400 if either is missing or not a number)
POST, DELETE	/mcp	The MCP server (JSON-RPC over Streamable HTTP; DELETE ends a session; GET is 405). Needs an OAuth access token (401 without one)
GET	/.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server	The MCP OAuth discovery documents (RFC 9728 and 8414)
POST	/oauth/register	Dynamic client registration (RFC 7591) for MCP clients
GET, POST	/oauth/authorize	Where an MCP client sends the user's browser: Gitea login if needed, then a consent page
POST	/oauth/token	Trades an authorization code (with its PKCE verifier) or a refresh token for tokens
GET	/api-docs	Swagger UI
GET	/swagger.json	OpenAPI/Swagger spec
GET	/auth/login	Starts the Gitea OAuth login (redirects to Gitea)
GET	/auth/callback	OAuth redirect target: completes the login, sets the session cookie, redirects to /
POST	/auth/logout	Ends the session
GET	/auth/me	The logged-in user, {:login "alice" :id 7 :admin? true} (401 if not logged in)
GET	/api/todos	Login required. Your todos: {:todos [{:id 1 :owner-id 7 :title "buy milk" :done false :created-at 1700000000000 :updated-at 1700000000000}]}
POST	/api/todos	Login required. Body {"title": "buy milk"} creates a todo and returns it with 201 (400 if the title is blank or over 200 characters)
GET	/api/todos/:id	Login required. One todo (404 if it doesn't exist or isn't yours)
PATCH	/api/todos/:id	Login required. Body with title and/or done ({"done": true}) updates the todo and returns it (400 for an empty or invalid change, 404 as above)
DELETE	/api/todos/:id	Login required. Deletes the todo: {:deleted true} (404 as above)
GET	/nrepl	Admin only. Whether the nREPL debug server is on: {:enabled false}, or {:enabled true :bind "127.0.0.1" :port 7888}
POST	/nrepl	Admin only. Body {"enabled": true} (JSON or EDN) starts the nREPL debug server, false stops it; returns {:enabled true :bind "127.0.0.1" :port 7888}

curl localhost:3000/api/ping           # pong
curl 'localhost:3000/api/add?x=2&y=3'  # {:result 5}
curl 'localhost:3000/api/add?x=2&y=3' -H 'Accept: application/json'  # {"result":5}

Formats

The API speaks EDN, JSON and Transit (application/transit+json, application/transit+msgpack). Responses follow the request's Accept header, and request bodies are read by their Content-Type. EDN is the default: with no Accept (or */*, or a type the API can't produce) you get EDN, and a body sent with no Content-Type is read as EDN. Errors (400, 401, 403, ...) use the same format as everything else. Two exceptions: /api/ping is always text/plain, and /swagger.json is always JSON.

Handlers return plain data ((tbd.http/respond 200 {:result 5})), and the muuntaja middleware in tbd.core encodes it; don't pr-str a body yourself.

Todos

Each logged-in user has their own todo list, keyed by their Gitea user id. Every query is filtered by that id, so users can't see or change each other's todos; someone else's todo answers 404, exactly like a missing one. Without a login the todo routes answer 401. The operations themselves (ownership, validation, storage) live in src/tbd/todo/service.clj, which the HTTP routes and the MCP tools both call, so they behave the same and are tested once; a route or tool only translates its request into a service call and the result into a response, and never touches the database.

Todos are stored in a local SQLite file, data/todo.db by default (git-ignored), which is created and migrated on the first todo request. Set TODO_DB_PATH to put it elsewhere. In Docker, mount a volume at that path (e.g. docker run -v tbd-data:/app/data ...), or the todos are lost with the container.

# after logging in in a browser, copy the `tbd-session` cookie value:
curl -XPOST localhost:3000/api/todos -H 'Cookie: tbd-session=...' \
     -H 'Content-Type: application/json' -d '{"title": "buy milk"}'
curl localhost:3000/api/todos -H 'Cookie: tbd-session=...'

MCP server

The server also speaks MCP (Model Context Protocol) at /mcp, built on PluMCP and running inside this same process; there is nothing extra to start. It uses the Streamable HTTP transport, and, like the todo API, it acts as the logged-in user: a client has to be approved by a user first (see below), and from then on every tool call knows who is calling.

claude mcp add --transport http tbd https://tbd.example.com/mcp   # <BASE_URL>/mcp

The first time the client connects it gets a 401, opens your browser, you log in with Gitea as usual and approve the client, and the client keeps its tokens from then on. It needs the Gitea login to be configured, including BASE_URL (which must be the address the client uses; without them /mcp answers 503 rather than being open).

It offers these tools: ping, add (the same logic as /api/add), whoami (which user this connection acts as, and whether they are an admin), and, on the caller's own todos (the same ones as /api/todos), list_todos, get_todo, create_todo, update_todo and delete_todo. To add a tool, add a tool to src/tbd/mcp/tools.clj; it should call the group's service (or pure core functions), not a database, and if the group has no service yet, that is the thing to add, so the HTTP routes can share it. Its arguments are described by the group's Malli schema in src/tbd/<group>/schema.clj, the same schema the HTTP routes use for their parameters, so a shape of data is written down once: the tool's input schema is generated from it, and the arguments a client sends are coerced and validated against it (plumcp only checks that required ones are present). A tool that touches a user's data or does something admin-only gets the caller from current-user there ({:login :id :admin? :client-id}), and must not trust anything else about who is asking.

(The UI has tools of its own for a browser agent, see below; they are not part of this server.)

Sessions are kept in memory, so they end when the server restarts (clients just re-initialize; their tokens are in the database and keep working). Server-to-client streaming (GET /mcp) is deliberately off: nothing here pushes messages, and the response would hang under Jetty. PluMCP needs JDK 21+.

Connecting an MCP client

tbd is its own OAuth 2.1 authorization server for /mcp (in src/tbd/oauth/), with the Gitea login as the way a user proves who they are. Gitea's own tokens never reach an MCP client, and the tokens tbd issues are worth nothing anywhere else. The flow is the one the MCP authorization spec describes, so any compliant client does it by itself:

1. POST /mcp with no token gets 401 and WWW-Authenticate: Bearer resource_metadata="<BASE_URL>/.well-known/oauth-protected-resource/mcp".
2. The client reads that document, then /.well-known/oauth-authorization-server, and registers itself at /oauth/register (dynamic client registration, public clients only).
3. It opens /oauth/authorize in the browser (authorization-code flow, PKCE S256 required). If you aren't logged in you go through the Gitea login first and come back; then a consent page names the client and the address you'll be sent back to, and asks you to Approve or Deny.
4. The client trades the code at /oauth/token for an access token (1 hour) and a refresh token (30 days, rotated on every use), and sends Authorization: Bearer ... on every /mcp request.

The consent page is what stops a stranger's client (anyone can register one) from getting a token by sending you a link: nothing is issued without your click. Redirect URIs must be https, http on localhost/127.0.0.1/[::1] (the port may vary), or an app's own scheme (cursor://...).

What's stored is in OAUTH_DB_PATH: registered clients, and for each approval the user and a hash of the current access and refresh tokens. To cut a client off, delete its row from grants. Admin-ness isn't in the token: it is looked up in ADMIN_USERS on every request, so removing someone from the list takes effect at once. A Gitea account that is disabled keeps working until its refresh token expires (up to 30 days without use) or its grant is deleted, since Gitea isn't asked again after the login.

Authentication and the admin API

Login is OAuth2 (authorization-code flow) against a Gitea instance. Anyone with a Gitea account can log in, but routes marked :admin? true (currently GET and POST /nrepl) also require the user to be on the ADMIN_USERS allowlist: 401 without a login, 403 for a logged-in non-admin. With no allowlist, nobody is an admin.

1. In Gitea (Settings > Applications) create an OAuth2 application, a confidential client, with the redirect URI <BASE_URL>/auth/callback.
2. cp .env-template .env and fill it in. script/server loads .env; for Docker use docker run --env-file .env. .env is git-ignored and kept out of the image.

Variable	Purpose
GITEA_URL, GITEA_CLIENT_ID, GITEA_CLIENT_SECRET	The Gitea OAuth2 application. Without all three (and BASE_URL), /auth/login answers 503
BASE_URL	Public URL of this app; an https:// one also marks the session cookie Secure. It is also the address of the MCP server: the OAuth issuer, and what MCP clients are told to use (<BASE_URL>/mcp)
ADMIN_USERS	Comma-separated Gitea usernames (case-insensitive) allowed to use the admin API
SESSION_SECRET	Signs and encrypts session cookies. Unset = a random key per start, so logins don't survive a restart
TODO_DB_PATH	SQLite file for the todo group (default data/todo.db)
OAUTH_DB_PATH	SQLite file for the MCP OAuth server: registered clients, codes and tokens (default data/oauth.db). Mount a volume for it in Docker too, or every MCP client has to be approved again after each restart
NREPL_PORT, NREPL_BIND	Where the debug nREPL listens (default 7888 on 127.0.0.1)

Sessions live in an encrypted, signed, HttpOnly, SameSite=Lax cookie and expire after 8 hours (enforced server-side). The cookie is stateless, so POST /auth/logout clears it in the browser but can't revoke a copy someone already captured; it just expires on its own.

The nREPL endpoint

# after logging in in a browser, copy the `tbd-session` cookie value:
curl -XPOST localhost:3000/nrepl -H 'Cookie: tbd-session=...' \
     -H 'Content-Type: application/json' -d '{"enabled": true}'
clj -Sdeps '{:deps {nrepl/nrepl {:mvn/version "1.2.0"}}}' -M -m nrepl.cmdline --connect --host 127.0.0.1 --port 7888

nREPL has no authentication and evaluates arbitrary code, so enabling it is effectively remote code execution for whoever can reach the port. It therefore binds to loopback by default; reach it through an SSH tunnel (or docker exec) rather than setting NREPL_BIND=0.0.0.0. Each enable/disable is logged with the admin's Gitea username. It stays on until an admin disables it (or the server restarts), so switch it off when you're done.

UI

ui/ is a re-frame app (ClojureScript, React 19 via Reagent) built with shadow-cljs. It has three pages, as tabs across the top. Each has its own address in the URL's fragment (/#/games, /#/todos, /#/ai-setup), so the server only ever serves /, and a page can be bookmarked or reloaded.

Tab	What's on it
Games	Tic-tac-toe (two players on one board, all client side), and a small calculator form that calls GET /api/add and shows the sum (or the server's validation error)
Todos	Your todo list (add, tick off, delete), backed by /api/todos. The tab only shows once you're logged in; its address shows a "Log in" prompt otherwise
AI setup	The claude mcp add ... command to copy (with this page's own address in it) and the steps to sign in, for adding the MCP server to Claude Code; and how to connect an MCP client to the page's own browser tools

A "Log in" / "Log out" link sits in the footer row next to the API docs links.

shadow-cljs compiles it into resources/public/js/ (git-ignored). The server serves that directory at /js, and serves resources/public/index.html, the shell that mounts the app, at /.

Task	What it does
script/ui-build	Optimized release build into resources/public/js
script/ui-watch	Rebuilds on every change, with hot reload; run script/server alongside and refresh the page

The Docker image builds the UI in its own stage, so docker build needs no local Node. The UI's tests run in another stage of the same Dockerfile (--target ui-test), which the server image doesn't include.

Browser MCP tools (WebMCP)

The page also offers tools of its own to your MCP client (Claude), through WebMCP: a small library that adds a widget to the page and lets the page register tools with it. They are the browser-side twin of the server's MCP tools: those work on your data on the server, these work the page, doing what you could do with the mouse and keyboard, so you see it happen. A tool that changes something opens the tab it acts on first (the todo tools open Todos, the game and calculator tools open Games). They are in ui/src/tbd/ui/webmcp.cljs, registered with registerTool on a WebMCP instance (the @jason.today/webmcp npm package):

Tool	What it does
ping, whoami	Health check; who is logged in on the page, if anyone
get_calculator	What the calculator form holds: its two fields and the result it shows
add	Types x and y into the calculator, presses Add, and returns the sum the page shows
list_todos, get_todo	The todos the page shows (login required, like the todo list itself)
create_todo	Types a title into the new-todo field, presses Add, returns the new todo
set_todo_done	Ticks or unticks a todo's checkbox (id, done)
delete_todo	Presses a todo's Delete button

Each tool dispatches the same re-frame events the views do and waits for the result to show up in the app-db, so what the agent sees is what the page shows, server errors included. There is no update_todo with a title as on the server, because the page can't edit one.

To connect (the page's "Browser tools (WebMCP)" section says the same):

1. Add the WebMCP server to your MCP client, once: npx -y @jason.today/webmcp@latest --config claude (restart Claude Desktop afterwards).
2. Ask the client to make a webmcp token.
3. Click the blue square in the bottom right corner of the page, paste the token, and press Connect. The token works once, and the page has no field for it: the widget is where it goes.
4. The tools show up in the client, prefixed with the page's host.

Development

Every task is a bash script in script/. Start an nREPL server (with CIDER middleware) on the port in .nrepl-port, or 3000 if that file doesn't exist:

script/repl

Tests

Task	What it does
script/unit-test	Runs the Clojure tests in test/
script/ui-test	Runs the ClojureScript tests in ui/test/ under Node, in a jsdom window (needs Node and a JDK)
script/integration-test	Builds the app image, starts it on a random port, runs the integration suite against it, then tears it down
script/test	UI tests, unit tests, then integration tests (stops at the first failure)
script/docker-unit-test	Same as script/unit-test, but inside the app image (Docker only)
script/docker-ui-test	Same as script/ui-test, but inside a Node + JDK image (Docker only)

The UI tests render the real app in jsdom against a fake server and drive it like a user (type, submit, click), next to plain tests of the re-frame events and subscriptions, the game rules and the WebMCP tools (ui/test/tbd/ui/; the shared fakes are in test_util.cljs). ui/test/dom-setup.cjs gives them a window and the real WebMCP library, and fails a run that hangs, rejects a promise nobody handles, or ends without a result (a test that never calls done would otherwise pass or stall silently). npm test in ui/ preloads it, so use that (or the scripts) rather than running the build's output directly.

Coverage

Line coverage of the Clojure code via Cloverage, and of the UI via c8:

Task	Output
script/unit-coverage	target/coverage/unit/
script/integration-coverage	target/coverage/integration/
script/ui-coverage	target/coverage/ui/ (V8 coverage of the compiled UI, mapped back to ui/src/**/*.cljs through the source maps)
script/coverage	Runs all three, then writes the merged Clojure report to target/coverage/merged/ (the UI's stays separate)
script/docker-unit-coverage, script/docker-ui-coverage, script/docker-coverage-report	Dockerized versions of the unit run, the UI run and the merge step, so script/docker-ui-coverage, script/docker-unit-coverage, script/integration-coverage, script/docker-coverage-report is script/coverage with no local Clojure, Node or Babashka (this is what CI runs)

Each report directory has an index.html and an lcov.info. The UI's numbers are approximate where one ClojureScript form compiles to several JavaScript blocks (a case or cond, say): a line can show as uncovered when only part of the form ran. See integration-test/README.md for how integration coverage is collected.

Project layout

src/tbd/
  core.clj            Router, Ring app, and server startup
  <group>/routes.clj  Each route group (health, math, ...) owns its route subtree
  <group>/core.clj    Business logic for the group, with no HTTP concerns
  <group>/schema.clj  Malli schemas of the group's input, shared by its routes and the MCP tools
  auth/               Gitea OAuth (core), session + admin middleware (middleware), /auth routes
  mcp/                MCP server (PluMCP) mounted at `/mcp`: tools (tools.clj), Malli-to-tool glue (schema.clj) and the Ring handler (routes.clj)
  oauth/              tbd as the OAuth authorization server for MCP clients: rules (core), SQLite storage (db), `/oauth` + discovery routes, and the bearer-token middleware guarding `/mcp` (middleware)
  nrepl/              On-demand nREPL server (core) and the admin-only `/nrepl` routes
  todo/               Per-user todos: pure rules (core), Malli schemas of the input (schema), SQLite storage (db), `/api/todos` routes
ui/                   ClojureScript re-frame app (shadow-cljs project); ui/src/tbd/ui/{db,events,subs,views,webmcp,core}.cljs, tests in ui/test/
.env-template         Settings the server reads from the environment; copy to .env (git-ignored)
resources/public/     index.html (the shell served at /) and js/ (compiled UI output, git-ignored)
test/                 Unit tests
integration-test/     Dockerized integration tests and coverage harness
script/               Bash entry points (server, ui-build, ui-test, test, coverage, repl, ...) and coverage helpers

To add a new group, create tbd.<group>.routes with a routes fn that returns a reitit route vector, then add it to the router in src/tbd/core.clj. To make a route admin-only, put :admin? true in its route data (admin allowlist), or :login? true (any logged-in user; the user is passed to the handler as :user). A group with storage keeps it in its own tbd.<group>.db, apart from its business logic in core.clj.