Fixyourdocs MCP Server

Licence

This repository is licensed under FSL-1.1-Apache-2.0. After 2 years (2028-05-22) each release automatically converts to Apache 2.0 per the FSL transition clause. See LICENSE for the full text and https://fsl.software for background.

FixYourDocs

A structured feedback channel between the AI agents that read your documentation and the humans who maintain it.

AI agents read documentation to help their users follow procedures. When they hit a gap, outdated section, contradiction, or dead end, today the signal is dropped: the user gets a worse answer and you never hear about it. FixYourDocs gives those agents a place to put the signal: they file a structured report through an open protocol, and the hub routes it — by the report's doc-URL host — to the repo of the maintainer who has verified (DNS-TXT) that they own that domain, opening a GitHub Issue so maintainers triage it with the tools they already use.

This repository contains the reference implementation of the hosted product running at fixyourdocs.io — SPA, REST API, and the MCP client package — alongside the docsfeedback.org Starlight site that hosts the open spec. The production CDK pipeline lives in a separate private infrastructure repository. The wire protocol it implements is specified in the open at docsfeedback.org.

Project layout (across the fixyourdocs/ org)

If you want to understand the protocol, start at fixyourdocs/protocol. If you want to emit reports from an agent, use one of the SDKs or drop in the AGENTS.md snippet. If you want to run your own backend, read on.

What's in this repo

• frontend/ — Vite + React + Tailwind v4 SPA: landing page, sign-up / sign-in, GitHub App install + target-repo setup.
• backend/ — REST API Lambdas (Node.js 20 / TypeScript). Public rate-limited /v1/reports* plus Cognito-protected /v1/orgs/* and /v1/integrations/*; an async-invoked forwarder Lambda turns each accepted report into a GitHub Issue.
• mcp-server/ — Client-side npm package (@fixyourdocs/mcp-server, run via npx -y @fixyourdocs/mcp-server over stdio) exposing a single file_doc_feedback tool. Calls POST https://hub.fixyourdocs.io/v1/reports to file a v0 report; the hub routes it to a GitHub Issue on the repo of the maintainer who has verified ownership of the doc's domain.
• docsfeedback-site/ — Starlight site for docsfeedback.org. Spec markdown and JSON schemas are synced from the protocol repo at build time.
• e2e/ — Playwright forwarder smoke test.
• SPEC.md — V1 product specification for this implementation. (For the protocol spec, see the protocol repo.)

Quickstart (local dev)

Requires Node.js 20 and pnpm 10.

pnpm install
pnpm -r typecheck
pnpm --filter @fyd/frontend dev               # SPA on http://localhost:5173
pnpm --filter @fyd/docsfeedback-site dev      # docs site on http://localhost:4321
pnpm --filter @fyd/e2e test                   # Playwright suite

The frontend points at whatever API_BASE_URL you configure at runtime via frontend/public/env.js (not committed — generate it at deploy time from your stack outputs).

Self-hosting

The production hosted variant runs on AWS Lambda + API Gateway HTTP API + DynamoDB + Cognito + CloudFront, deployed via AWS CDK v2. The CDK app itself is operated from a separate private infrastructure repository; a public reference template will follow once the hosted variant is stable.

Self-hosters writing their own CDK app today can match the contract by passing the following env vars through to the backend Lambdas:

Using FixYourDocs from an agent

The agent-facing surface is the hub's POST https://hub.fixyourdocs.io/v1/reports endpoint. Reports are anonymous (rate-limited by IP) and conform to the v0 schema specified at docsfeedback.org/spec/v0 and in the protocol repo.

Two ways to wire an agent to it:

• Drop-in AGENTS.md block — paste the snippet from fixyourdocs/agents-md-snippet into your project's AGENTS.md / CLAUDE.md / .cursorrules. Works with any agent that reads those files; no MCP client required.
• MCP client — use one of the SDKs (Python, TypeScript) or the helper in mcp-server/ to expose a file_doc_feedback tool to clients that speak MCP (Claude Desktop, Cursor, …).

Contributing

PRs welcome. We use the standard Developer Certificate of Origin — sign your commits with git commit -s. Issues against this repo should be about the implementation; issues against the protocol repo should be about the wire format.

A CLA is required for non-trivial contributions (see fixyourdocs/.github for the text); the CLA-assistant bot will post a sign-off link on your first PR.

Licence

FSL-1.1-Apache-2.0. The Functional Source License keeps the code source-available with a non-compete carve-out for two years, then automatically converts each release to Apache 2.0. See LICENSE and fsl.software.

The protocol itself, the SDKs, and the AGENTS.md snippet ship under permissive licences (Apache 2.0 / CC-BY 4.0) so the open spec stays unencumbered regardless of what this repo does. See each repo's own LICENSE.