# FixYourDocs

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/fixyourdocs/fixyourdocs  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/fixyourdocs

## Description
File structured docs-feedback reports to the FixYourDocs hub via a file_doc_feedback tool.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "fixyourdocs": {
    "command": "npx",
    "args": ["-y","fixyourdocs"]
  }
}
```

## Documentation & README

## 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 — 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.

This 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).

## Project layout (across the `fixyourdocs/` org)

| Repo | Purpose | Licence |
|---|---|---|
| [**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 |
| [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) |
| [fixyourdocs/sdk-python](https://github.com/fixyourdocs/sdk-python) | Reference Python SDK for the protocol | Apache-2.0 |
| [fixyourdocs/sdk-typescript](https://github.com/fixyourdocs/sdk-typescript) | Reference TypeScript SDK for the protocol | Apache-2.0 |
| [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 |
| [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) |

If 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.

## What's in this repo

- [frontend/](frontend/) — Vite + React + Tailwind v4 SPA: landing page, sign-up / sign-in, GitHub App install + target-repo setup.
- [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.
- [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.
- [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.
- [e2e/](e2e/) — Playwright forwarder smoke test.
- [SPEC.md](SPEC.md) — V1 product specification for this implementation. (For the **protocol** spec, see the [protocol repo](https://github.com/fixyourdocs/protocol).)

## Quickstart (local dev)

Requires Node.js 20 and pnpm 10.

```sh
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:

| Variable | Required | Notes |
|---|---|---|
| `CDK_DEFAULT_ACCOUNT` (or `FYD_AWS_ACCOUNT`) | yes | Target AWS account ID. |
| `CDK_DEFAULT_REGION` (or `FYD_AWS_REGION`) | no | Defaults to `us-east-1`. Don't change unless you understand the CloudFront cert constraint. |
| `FYD_ROOT_DOMAIN` | no | Defaults to `fixyourdocs.io`. The SPA, API, and Cognito callback URLs derive from it. |
| `FYD_HOSTED_ZONE_ID` | yes | Route 53 hosted zone ID for `FYD_ROOT_DOMAIN`. |
| `FYD_OPS_ALERT_EMAIL` | yes | Subscribed to CloudWatch alarms + billing budget. |
| `FYD_GITHUB_REPO` | no | `org/repo` allowed to assume the OIDC deploy role. |
| `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). |
| `FYD_STACK_PREFIX` | no | Prefix applied to all stack names. |

## 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](https://docsfeedback.org) and in the [protocol repo](https://github.com/fixyourdocs/protocol).

There are two adoption modes:

- **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.
- **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.

In 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.

## Contributing

PRs 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**.

A 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.

## 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](LICENSE) and [fsl.software](https://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.