Content
# Auto-Documentation MCP Server
Production-ready TypeScript MCP server that captures development signals and continuously builds user/admin documentation in Notion.
The local bridge uses HTTP-SSE transport:
- `GET /sse` opens the MCP session stream
- `POST /messages?sessionId=...` sends JSON-RPC tool calls for that session
- `GET /health`, `GET /info`, `GET /startup/preflight`, and `GET /contracts/bifrost-discovery` expose runtime and contract checks
## Quick Start
For a full cold-start path from clone to a first generated manual, use [QUICKSTART.md](QUICKSTART.md).
1. Install dependencies:
```bash
npm ci
```
2. Run checks:
```bash
npm run lint
npm run typecheck
npm test
npm run build
```
3. Run locally:
```bash
npm run dev
```
## Environment
- `NOTION_TOKEN` for Notion API access
- `NOTION_PARENT_PAGE_ID` for live integration tests
- `RUN_LIVE_NOTION_TESTS=true` to enable env-gated live tests
- `BIFROST_VIRTUAL_KEY` for Bifrost-backed AI calls when the provider is `bifrost`
- `AUTO_DOC_BRIDGE_API_KEY` for HTTP-SSE bridge access; required to open `/sse`, `/runner/status`, and `/runner/trigger`
- `AUTO_DOC_RUNNER_PROJECT_ID` and `AUTO_DOC_RUNNER_REPO_PATH` to enable the continuous runner
- `AUTO_DOC_RUNNER_TARGETS` to configure multiple runner targets in one JSON payload
- `SELF_DOC_PROJECT_ID` and `SELF_DOC_REPO_PATH` are separate runtime config values; they are not the runner source of truth
- `STATE_ENCRYPTION_KEY` must be a unique high-entropy value in production, bridge mode, and runner mode
- Project state defaults to `~/.auto-doc-mcp/state.json` so runner restarts resume the same project outside the current working directory
- `AUTO_DOC_STATE_FILE` is optional and should be set only for isolated test/staging environments; explicit overrides do not auto-migrate legacy state
- `discover_project_from_notion` can rebuild a local project binding from an existing Auto-Doc Notion project page after validating all five databases and relations
- `AUTO_DOC_DISCOVERY_RECOVERY_ENABLED=true` plus `AUTO_DOC_DISCOVERY_PROJECT_PAGE_ID` or `AUTO_DOC_DISCOVERY_PAGE_HINTS` enables guarded runner recovery after `project_missing_from_state`; it is disabled by default
- `AUTO_DOC_ARTIFACT_ROOT` constrains generated PDFs, local docs, help-center exports, and screenshots
Generate a production state key:
```bash
node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
```
## Runtime Modes
Container default: HTTP bridge mode. The Docker image starts `node build/src/cli/index.js bridge`, exposes `/health`, and is intended for web, Bifrost, and tunnel deployments. Set `AUTO_DOC_BRIDGE_API_KEY` before opening MCP or runner sessions; non-loopback binds fail closed without a configured, non-placeholder key.
Use stdio MCP locally with `npm run dev` or `node build/src/index.js`. Use continuous mode with `AUTO_DOC_RUNTIME_MODE=runner node build/src/index.js` or `node build/src/cli/index.js runner` after configuring runner targets.
## VS Code MCP Development Integration
This repository includes local MCP workspace configuration in:
- `.mcp.json`
- `.vscode/mcp.json`
The default connection runs this server directly over stdio:
```json
{
"command": "node",
"args": ["build/src/index.js"]
}
```
Before running your MCP client in development:
1. Run `npm ci`.
2. Run `npm run build`.
3. Ensure your `.env` contains `NOTION_TOKEN`, `NOTION_PARENT_PAGE_ID`, and `STATE_ENCRYPTION_KEY`.
4. Restart your MCP client/IDE so the server entry is reloaded.
HTTP-SSE bridge mode remains available for web or remote clients. See [QUICKSTART.md](QUICKSTART.md) for bridge setup, Notion setup, provider configuration, and first tool calls.
## CI
GitHub Actions runs typecheck, lint, tests, build, and a Docker bridge smoke test on pushes and pull requests to `main`.
## Branch Protection
Enforce merge protection on `main` so CI must pass before merge:
- Required status check: `test-build`
- Require branch to be up to date before merge
- Require at least one approving pull request review
Apply these settings with the included script:
1. Set a GitHub admin token:
```bash
export GITHUB_ADMIN_TOKEN=<your-admin-token>
```
2. Run:
```bash
./scripts/apply-branch-protection.ps1 -Owner bido75 -Repo Auto-Documentation-MCP-Server
```
3. Read-only verification:
```bash
./scripts/apply-branch-protection.ps1 -Owner bido75 -Repo Auto-Documentation-MCP-Server -VerifyOnly
```
See full policy details in `docs/branch-protection.md`.
## CD Releases
GitHub Actions publishes a release when you push a semantic version tag (`v*.*.*`).
Release workflow:
- Runs `typecheck`, `test`, and `build`
- Verifies the tag commit is on `main`
- Verifies required CI check `test-build` already passed
- Packages a release artifact from `build/` plus runtime metadata files
- Publishes a GitHub Release with autogenerated notes
Create and push a release tag:
```bash
git tag v1.0.0
git push origin v1.0.0
```
You can also run the Release workflow manually from GitHub Actions using a tag input.
## GitHub Push Setup (Required Once)
This repository is configured to push through SSH.
1. Confirm remote URL:
```bash
git remote -v
```
You should see `git@github.com:bido75/Auto-Documentation-MCP-Server.git`.
2. Generate an SSH key (if needed):
```bash
ssh-keygen -t ed25519 -C "bido75@users.noreply.github.com"
```
3. Copy your public key:
```bash
cat ~/.ssh/id_ed25519.pub
```
4. Add the key in GitHub:
- GitHub Settings -> SSH and GPG keys -> New SSH key
5. Verify auth:
```bash
ssh -T git@github.com
```
6. Push:
```bash
git push -u origin main
```
## Optional Auto-Push
This repo includes a `post-commit` git hook in `.githooks/post-commit` that attempts to push after each commit on `main`.
Enable it locally:
```bash
git config core.hooksPath .githooks
```
If push auth is not configured yet, the hook prints the error and retries once.
