{
  "markdown": "## Licence\nThis repository is licensed under FSL-1.1-Apache-2.0. After 2 years (2028-05-22)\neach release automatically converts to Apache 2.0 per the FSL transition clause.\nSee LICENSE for the full text and https://fsl.software for background.\n\n# FixYourDocs\n\n> A structured feedback channel between the AI agents that read your documentation and the humans who maintain it.\n\nAI 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 — to the repo of the maintainer who has verified that they own those docs (a domain, or a GitHub Pages site), opening a GitHub Issue so maintainers triage it with the tools they already use.\n\nThis repository contains the **reference implementation** of the hosted product running at [fixyourdocs.io](https://fixyourdocs.io) — SPA, REST API, and the MCP client package — alongside the [docsfeedback.org](https://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](https://docsfeedback.org).\n\n## Project layout (across the `fixyourdocs/` org)\n\n| Repo | Purpose | Licence |\n|---|---|---|\n| [**fixyourdocs/fixyourdocs**](https://github.com/fixyourdocs/fixyourdocs) (this repo) | Hosted product (SPA + REST API + MCP package) and the `docsfeedback.org` Starlight site | FSL-1.1-Apache-2.0 |\n| [fixyourdocs/protocol](https://github.com/fixyourdocs/protocol) | Open spec of the Docs Feedback Protocol — message shapes, JSON Schemas, versioning | Apache-2.0 (code) + CC-BY 4.0 (prose) |\n| [fixyourdocs/sdk-python](https://github.com/fixyourdocs/sdk-python) | Reference Python SDK for the protocol | Apache-2.0 |\n| [fixyourdocs/sdk-typescript](https://github.com/fixyourdocs/sdk-typescript) | Reference TypeScript SDK for the protocol | Apache-2.0 |\n| [fixyourdocs/agents-md-snippet](https://github.com/fixyourdocs/agents-md-snippet) | Drop-in `AGENTS.md` / `CLAUDE.md` / `.cursorrules` block that teaches an agent to file reports | Apache-2.0 |\n| [fixyourdocs/manifesto](https://github.com/fixyourdocs/manifesto) | The \"why\" — the case for an open protocol between agents and docs maintainers | Apache-2.0 (code) + CC-BY 4.0 (prose) |\n\nIf you want to **understand the protocol**, start at [fixyourdocs/protocol](https://github.com/fixyourdocs/protocol). If you want to **emit reports from an agent**, use one of the SDKs or drop in the [AGENTS.md snippet](https://github.com/fixyourdocs/agents-md-snippet). If you want to **run your own backend**, read on.\n\n## What's in this repo\n\n- [frontend/](frontend/) — Vite + React + Tailwind v4 SPA: landing page, sign-up / sign-in, GitHub App install + target-repo setup.\n- [backend/](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.\n- [mcp-server/](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.\n- [docsfeedback-site/](docsfeedback-site/) — Starlight site for [docsfeedback.org](https://docsfeedback.org). Spec markdown and JSON schemas are synced from the [protocol repo](https://github.com/fixyourdocs/protocol) at build time.\n- [e2e/](e2e/) — Playwright forwarder smoke test.\n- [SPEC.md](SPEC.md) — V1 product specification for this implementation. (For the **protocol** spec, see the [protocol repo](https://github.com/fixyourdocs/protocol).)\n\n## Quickstart (local dev)\n\nRequires Node.js 20 and pnpm 10.\n\n```sh\npnpm install\npnpm -r typecheck\npnpm --filter @fyd/frontend dev               # SPA on http://localhost:5173\npnpm --filter @fyd/docsfeedback-site dev      # docs site on http://localhost:4321\npnpm --filter @fyd/e2e test                   # Playwright suite\n```\n\nThe 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).\n\n## Self-hosting\n\nThe 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.\n\nSelf-hosters writing their own CDK app today can match the contract by passing the following env vars through to the backend Lambdas:\n\n| Variable | Required | Notes |\n|---|---|---|\n| `CDK_DEFAULT_ACCOUNT` (or `FYD_AWS_ACCOUNT`) | yes | Target AWS account ID. |\n| `CDK_DEFAULT_REGION` (or `FYD_AWS_REGION`) | no | Defaults to `us-east-1`. Don't change unless you understand the CloudFront cert constraint. |\n| `FYD_ROOT_DOMAIN` | no | Defaults to `fixyourdocs.io`. The SPA, API, and Cognito callback URLs derive from it. |\n| `FYD_HOSTED_ZONE_ID` | yes | Route 53 hosted zone ID for `FYD_ROOT_DOMAIN`. |\n| `FYD_OPS_ALERT_EMAIL` | yes | Subscribed to CloudWatch alarms + billing budget. |\n| `FYD_GITHUB_REPO` | no | `org/repo` allowed to assume the OIDC deploy role. |\n| `FYD_COGNITO_DOMAIN_PREFIX` | no | Cognito Hosted UI prefix. Defaults to `fyd-auth-${account}` so deployments don't collide (Cognito prefixes are globally unique per region). |\n| `FYD_STACK_PREFIX` | no | Prefix applied to all stack names. |\n\n## Using FixYourDocs from an agent\n\nThe 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](https://docsfeedback.org) and in the [protocol repo](https://github.com/fixyourdocs/protocol).\n\nThere are two adoption modes:\n\n- **Mode A — first-party (paste into your repo).** Paste the snippet from [fixyourdocs/agents-md-snippet](https://github.com/fixyourdocs/agents-md-snippet) into your project's `AGENTS.md` / `CLAUDE.md` / `.cursorrules`. Agents working **in your repo** offer to report **your repo's** broken docs — showing you the report and sending it only once you confirm. Works with any agent that reads those files; no MCP client required.\n- **Mode B — consumer-side (install into your own agent).** Install [`@fixyourdocs/mcp-server`](mcp-server/) into your **own, global** agent/client config (Claude Desktop, Cursor, Codex, …). While you work on something unrelated, your agent can **offer** — with your confirmation, and on public docs only — to report the **third-party** docs it consulted that turned out to be broken, even if that project never added the snippet. The MCP server is the primary Mode B carrier; the consent prompt and the privacy/opt-out guards (refuse non-public `doc_url`s; honour a doc host's `/.well-known/docs-feedback.json` opt-out before anything leaves your machine) are enforced by the SDK client it builds on.\n\nIn both modes the **receiver** (the docs owner) still has to claim and verify the docs they own — a domain (via DNS-TXT) or a GitHub Pages site (via the GitHub App on the publishing repo) — and install the hub integration to receive anything — Mode B only removes the *reporting-side* install requirement. The SDKs ([Python](https://github.com/fixyourdocs/sdk-python), [TypeScript](https://github.com/fixyourdocs/sdk-typescript)) and the helper in [`mcp-server/`](mcp-server/) implement the `file_doc_feedback` path for both.\n\n## Contributing\n\nPRs welcome. We use the standard [Developer Certificate of Origin](https://developercertificate.org/) — sign your commits with `git commit -s`. Issues against this repo should be about the **implementation**; issues against the [protocol](https://github.com/fixyourdocs/protocol) repo should be about the **wire format**.\n\nA CLA is required for non-trivial contributions (see [fixyourdocs/.github](https://github.com/fixyourdocs/.github) for the text); the CLA-assistant bot will post a sign-off link on your first PR.\n\n## Licence\n\nFSL-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](LICENSE) and [fsl.software](https://fsl.software).\n\nThe **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.\n",
  "bytes": 8971,
  "sha": "c22f3a1c49b74364d2214059e0e18f2df4d698ebcd33ad67ab7d3e00e38d7062",
  "repo_slug": "fixyourdocs/fixyourdocs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_fixyourdocs_mcp_server_ac028033/readme"
}