FastSpec
Open-source app for writing, versioning, diffing and linting OpenAPI specs, with an MCP server so AI agents can work with them. FastAPI and Vue, self-hosted from one Docker image or serverless on AWS for cents a month.
Highlights
- Open source under AGPL-3.0Public repo with its history kept and scrubbed, released as a multi-arch Docker image on GHCR.
- $17 to $0.03 a month idleThe hosted database moved from an RDS instance stopped when idle to Neon's free plan, which scales to zero and wakes in under a second.
- 11 MCP tools for AI agentsClaude Code or Cursor read, write, version, compare and lint specs, with an API key scoped per action.
- One docker run to try itOne image serves the app, API and MCP server on one port, on SQLite with no sign-in, and migrates itself on start.
Overview
FastSpec is a web app for writing and maintaining OpenAPI specs. You build a spec in a form or as YAML or JSON, preview it in Swagger UI, save it as named versions, diff any two of them, and lint it with Spectral against your own house rules. An MCP server lets AI agents such as Claude Code or Cursor read, write, version and lint your specs with a scoped API key.

It is the spec-first counterpart to FastMock, which mocks an API from the models a FastAPI app already declares. FastSpec has been open source (AGPL-3.0) since v0.1.0 on 27 September 2026. It runs from one Docker image, or as a hosted version at fastspec.kaseovo.com. Every screenshot below comes from the app running locally against fictional specs.
Problem
- OpenAPI is easy to get subtly wrong by hand. Path parameters,
$refs and array item schemas all have to line up, and Swagger UI often fails quietly when they don’t. - Reviewers need changes in API terms. “An endpoint was removed” and “a schema field became required” matter; a JSON text diff buries them.
- Custom lint rules are a code execution risk. Spectral rulesets can load JavaScript from disk and fetch other rulesets from URLs, so accepting them from users as-is means running their code on the server.
- AI clients need their own credential. Handing an assistant the user’s web session is not acceptable; access has to be scoped and revocable.
- Trying it has to take one command. Until September 2026, running it locally meant an AWS emulator, the AWS CDK and a Google OAuth client of your own.
- It is a side project. The AWS bill has to be close to zero when nobody is using it, without giving up a real managed Postgres.
Approach
I built FastSpec with AI coding agents in the loop (Claude Code, and GitHub’s
Copilot agent for some issues), so the repo is written to be read by an agent
as much as by me. AGENTS.md lists the test commands and what the common
failures mean, CONTEXT.md is a glossary of domain terms (Path Parameter
Token, Lint Ruleset, Spec Version Mode), and every architecture decision is an
ADR. Once the feature set was in place I ran a full-repo review and worked
through it.
The rule the codebase follows throughout: the why lives next to the code.
Module docstrings point at the ADR or review section that explains them.
database.py, for example, cites ADR-0009 for why the hosted database’s quota
errors get their own message instead of “try again shortly”. A deliberate
trade-off then can’t get “fixed” by accident, by me or by an agent.
Going open source followed the same habit. docs/ROADMAP.md records each
decision with its reason (license, sign-in, database, what to do with the git
history) and ticks off the work as it lands. Every release has a changelog
entry.
What I built
Form editorDoneA full spec can be built without touching JSON, and path parameters can't drift from the path string.
GoalLet someone write a complete OpenAPI spec without knowing its JSON shape by heart, with the code and a live Swagger preview one click away.
The editor is three views over one spec object: a form, the code in Monaco (YAML or JSON), and a Swagger UI preview. Most of the work went into the form. Info, servers, paths, tags, component schemas and security each get a section with search, and adding a path, an operation or a schema goes through a short wizard instead of an empty JSON block.

Path parameters are the one thing the form won’t let you edit directly. Type
/loans/{loanId}/return and a required loanId path parameter appears;
remove the token and the parameter goes too, after a confirmation if you had
filled it in. The path string is the only source, so the two can’t disagree.

Versions and diffDoneAny two versions, or a draft and a version, diff by endpoint, schema, server and info, and export as Markdown.
GoalMake every save a reviewable change: show what moved between two versions, or between a draft and what's stored, before anything is written.
Every spec keeps named versions. The backend diff compares two of them in API terms: endpoints added, removed or modified, schema fields added, removed or changed, plus servers and info. The same comparison runs against an unsaved draft, which is what the save dialog uses. Before anything is written, you see what changed and the lint score the new version would get. The report also exports as Markdown, for a PR description or a changelog.


Linting with custom rulesDoneSpecs lint against Spectral's OpenAPI rules plus named custom rulesets, with no path to run user code.
GoalCatch spec problems before an API consumer does, with house rules a team can write without learning Spectral's YAML and without being able to run code on the server.
Linting runs the Spectral CLI, installed in the backend’s Docker image, against
a stored spec or an unsaved draft. Spectral’s spectral:oas rules always
apply. On top of them, a user keeps any number of named rulesets, marks one as
the default, and can pin another to a specific spec: a strict one for a public
API, a looser one for an internal one. In the code view, each finding’s marker
is placed by its JSON path, so it lands on the right line in YAML and in JSON.
Rules are built in a form (severity, a JSONPath target from presets, a function and its options), with a raw YAML tab for what the form can’t express. “Test against current spec” runs one draft rule on its own, without the baseline rules, so you see exactly what it matches before saving.


Rule functions
- Chose
- Spectral's ten built-in functions only
- Instead of
- Custom JavaScript functions
- Why
- Spectral loads custom functions from disk and runs them. Accepting them from users would be remote code execution, so raw YAML with functions or functionsDir is rejected at save time.
extends
- Chose
- Only spectral: rulesets
- Instead of
- Any extends target
- Why
- extends can point at a URL, which would let a user make the server fetch arbitrary addresses (SSRF).
Ruleset scope
- Chose
- Many named rulesets per user, one default, an optional pin per spec
- Instead of
- One ruleset per user
- Why
- A public API and an internal one rarely want the same rules. Resolution is the spec's pinned ruleset, else the default, else the baseline alone.
MCP server for AI clientsDoneAn API key scoped by action reads, writes, versions, compares and lints its owner's specs through eleven MCP tools.
GoalLet an AI assistant work with a user's specs directly, with a credential the user can scope and revoke, and without ever touching their web session.
A FastMCP server runs in the same app at /mcp. It started with three read
tools (who_am_i, get_saved_specs_for_user and get_spec_details). v0.1.0
added tools to create and delete specs, list, read and save versions, compare
two of them, validate and lint, all reusing the services behind the HTTP API.
AI clients never see the web session. Instead, a user creates an API key in
the app, picks what it may do (read:specs, write:versions, lint:specs
and so on), and adds it with the MCP URL to their client. Each tool declares
the actions it needs, and a middleware checks them before the call runs.

Client credential
- Chose
- A long-lived API key, exchanged for a 5-minute JWT
- Instead of
- The user's web session, or verifying the key on every call
- Why
- The key is hashed at rest and revocable. Clients can reuse the short JWT instead of paying for a hash check per request, and revoking the key also kills the JWTs issued from it.
Key lookup
- Chose
- A salted hash plus the key's first 12 characters
- Instead of
- The hash alone
- Why
- A salted hash cannot be looked up by value. Without the prefix, each call would verify against every stored key.
Web sign-in
- Chose
- A full-page Authorization Code redirect
- Instead of
- Google's popup and One Tap flow
- Why
- Brave's popup blocker stopped the popup, so some people couldn't sign in at all. A redirect has nothing to block, and the same flow became the generic OIDC sign-in in v0.1.0.
Serverless on AWSDoneLambda, S3/CloudFront and an RDS instance that stopped itself after two idle hours, all from one CDK app. A serverless Postgres replaced RDS in September 2026.
GoalHost a multi-user app on AWS that costs close to nothing while nobody uses it, and run the same infrastructure code on my laptop.
The infrastructure started as one CDK app in TypeScript, in five stacks: RDS
Postgres; the backend as a Docker-image Lambda behind a Function URL; the ACM
certificate; S3 and one CloudFront distribution for the SPA and the landing
page; and the wake and auto-stop Lambdas. Migrations run inside the backend
Lambda, which the deploy workflow invokes with {"migrate": true}. Locally,
the same CDK code deploys into floci, a free AWS emulator. Since v0.1.0 that’s
only needed to work on the AWS deployment itself.
Compute
- Chose
- Docker-image Lambda behind a Function URL
- Instead of
- ECS Fargate behind an ALB, with ElastiCache
- Why
- The Fargate version ran first, but an ALB and a cache node bill by the hour even with no traffic. Lambda costs nothing between requests, and Redis came out with it.
Local environment
- Chose
- The same CDK stacks deployed into floci
- Instead of
- docker-compose, or LocalStack
- Why
- docker-compose had drifted from the real stack. LocalStack's free edition now needs an auth token; floci doesn't.
Database network
- Chose
- Public RDS endpoint, SSL forced, generated master password
- Instead of
- Lambda in a VPC with a NAT Gateway
- Why
- A NAT Gateway is about $32 a month, more than the RDS instance cost while stopped most of the day. ADR-0002 recorded the trade-off; ADR-0009 retired it along with RDS.
Wake page (landing site)
- health check first — goes straight to the app if the backend already answers
- otherwise — POSTs to the wake Lambda and polls until the app is up (about 2 minutes)
Wake Lambda
- starts RDS — and stamps wake-last-triggered in SSM
- 60-minute cooldown — repeat clicks while waking are no-ops
Backend Lambda
- every cold start — refreshes the same SSM timestamp
Auto-stop Lambda
- every 30 minutes — stops RDS once the timestamp is over two hours old
- DLQ and error alarm — a failed stop would silently keep the database billing
Self-hosting and open sourceDonev0.1.0 on 27 September 2026: one Docker image, SQLite or Postgres, no sign-in or any OIDC provider, under the AGPL-3.0.
GoalMake FastSpec something a stranger can try with one command and read the code of, without a Google Cloud project, an AWS account or a Postgres server.
The root Dockerfile builds the SPA, installs a pinned Spectral CLI and serves
everything on port 8080. In production, CloudFront sends /specs to S3 and
/api, /auth and /mcp to the Lambda; frontdoor.py does the same routing
inside the app, so sign-in behaves the same in both. With no configuration,
the container runs in single-user mode on SQLite, applies its migrations and
generates its JWT secret into /data. Each release publishes it for amd64
and arm64.
The same release made the editor worth trying on a real spec: YAML editing (specs are still stored as JSON), import by dropping, choosing or pasting a file, download as YAML or JSON, a Petstore example on the first visit, and Swagger UI bundled instead of loaded from a CDN. Before publishing, ruff and ESLint went from about 300 and 1,500 findings to none, enforced in CI, and the backend’s dependencies were pinned.

Sign-in
- Chose
- AUTH_MODE=none, or any OpenID Connect provider
- Instead of
- Google only, or built-in passwords
- Why
- Nobody should need a Google Cloud project to try it. One OIDC code path covers Keycloak, Authentik, Okta, Entra, GitLab and Google; passwords would mean storing them, resets and brute-force protection.
Database
- Chose
- SQLite by default, Postgres when DATABASE_URL is set
- Instead of
- Postgres only
- Why
- One docker run becomes a complete install, and a backup is one file. The cost: every migration has to run on both, which CI checks.
License
- Chose
- AGPL-3.0
- Instead of
- MIT
- Why
- While the hosted version exists, it stops anyone from running a closed, modified copy as a service. Relaxing a license later is easy; tightening it is not.
Git history
- Chose
- Kept, scrubbed, in a new repository
- Instead of
- Publishing it as is, or one squashed commit
- Why
- git filter-repo replaced the AWS account ID, hosted-zone ID, certificate ARN and author email, and blame survived. A new repository, because the old pull requests pinned the old commits.
Near-zero hosting costDoneNeon's free plan instead of RDS: an idle month costs about $0.03, and the first request after 5 idle minutes waits under a second.
GoalBring the hosted version's idle month from about $17 down to cents, without a multi-minute wake-up.
A stopped RDS instance still cost about $17 a month. RDS bills the provisioned disk (100 GB, the CDK default) and backups while stopped, and AWS restarts a stopped instance after seven days anyway. Waking it took one to three minutes.
The backend now takes any Postgres as a connection string from SSM. The hosted version uses Neon’s free plan in AWS Singapore: it scales to zero after 5 idle minutes and resumes on the next connection in under a second, so there is nothing left to wake. The data and wake stacks, the wake page and the “waking up” screen were deleted, and moving the domain’s DNS to Cloudflare, where the parent domain already lived, removed FastSpec’s Route 53 zone.
v0.3.0 then added an email on every first sign-in, through an SNS topic, and cut the backend’s log retention to 30 days, since sign-in logs can hold email addresses.
Database
- Chose
- Neon's free plan, a serverless Postgres
- Instead of
- RDS, stopped when idle and woken on demand
- Why
- Over its limits the free plan pauses the database or blocks writes; it never bills. The data now lives outside AWS, but moving is a pg_dump and one SSM parameter away.
Free-plan limits
- Chose
- A banner in the app and a daily usage check
- Instead of
- Generic 'database unavailable' errors
- Why
- Neon sends no warning. The backend recognises its quota errors and answers 503 or 507 with a plain explanation, and a workflow fails above 80% storage so GitHub emails me.
Sign-up email
- Chose
- An SNS topic, subscribed by hand
- Instead of
- A subscription in the CDK stack
- Why
- The address would land in the public template and the deploy workflow's cdk diff output. Self-hosted instances leave the topic unset and send nothing.
Tech stack
Languages
- Python
The backend, the MCP server and a small CLI that migrates and serves, or moves single-user data to a signed-in account.
Frameworks
- FastAPI
Specs, versions, lint and auth routers, split into routers, services and repositories. In the Docker image, the MCP server and the built SPA sit behind the same app, routed by a small front door.
Topics
- SQLAlchemy + Alembic
ORM and migrations, written to run on both SQLite and Postgres. They run on container start, or inside the backend Lambda on deploy.
- PostgreSQL
For teams through docker-compose, or any managed Postgres passed as DATABASE_URL. The hosted version runs on Neon.
- Neon
Serverless Postgres for the hosted version, on the free plan in AWS Singapore (0.5 GB, 100 compute-hours a month). It scales to zero after 5 idle minutes, resumes in under a second, and pauses rather than bills when over its limits.
- SQLite
The zero-configuration default in the Docker image: one file under /data, with foreign keys, WAL and a busy timeout turned on.
- OpenID Connect
Authorization Code with PKCE against any provider that publishes discovery metadata. Google is just one issuer URL.
- Spectral
The OpenAPI linter, pinned to 6.16.3 in both images and run per request against a generated ruleset file.
- FastMCP
Eleven tools to read, create, version, compare, validate and lint specs, each gated by the API key's actions. Stateless, one handler per request.
- Vue 3 + PrimeVue
The single-page editor, with Pinia for auth state and composables holding the form editor's logic.
- Monaco + Swagger UI
The YAML or JSON code view and the live preview, both over the same spec object as the form. Swagger UI is bundled, not loaded from a CDN.
- Docker
One image for linux/amd64 and linux/arm64 on GHCR, serving the app, API and MCP server on one port.
- AWS Lambda
The backend as a Docker-image Lambda behind a Function URL, adapted with Mangum; secrets fetched from SSM at cold start.
- S3 + CloudFront
One distribution routing to the SPA bucket, the landing-page bucket and the Lambda.
- AWS CDK
Three TypeScript stacks (backend Lambda, certificate, frontend), covered by 51 assertion tests and deployable into the floci emulator with the same code.
- GitHub Actions
Tests on SQLite and Postgres, smoke tests of both images, gitleaks, releases to GHCR, the AWS deploy and a daily database usage check.
- pytest + Vitest + Jest
Backend, frontend and infra suites of 248, 352 and 51 tests. Five backend tests need a real Postgres, which CI provides.
Future improvements
- The diff ignores parameters. It compares summaries and request and response schemas, so a new query parameter doesn’t show up as a change.
- Lint pays a Node cold start per call. An HTTP sidecar transport exists
in
spectral_client.pywith no server behind it yet, and results aren’t cached by spec and ruleset hash. - YAML comments don’t survive a save. Specs are stored as JSON, so keeping them means storing the raw text and reworking versions and diff.
- The hosted app connects as the database owner. The least-privilege
fastspec_approle exists as a migration, but it only runs whenFASTSPEC_APP_DB_PASSWORDis set, and the Neon deployment doesn’t set it. - The hosted database keeps 6 hours of history. Neon’s free plan has no long-term backup, so anything worth keeping has to be exported.
- One OIDC provider at a time, and no GitHub sign-in. GitHub doesn’t support OIDC for user sign-in, so it would need its own OAuth2 provider.