npm package: @kmahler0202/autodocs
Description: Self-maintaining MCP documentation servers for AI coding agents
Latest version: 1.0.0

# AutoDocs

> Give your AI coding agent a brain. Keep it alive automatically.

AutoDocs turns any codebase into a self-maintaining MCP (Model Context Protocol) documentation server — generated by Claude Code, kept in sync by GitHub Actions, reviewed by humans.

---

## The Problem

AI coding agents like Claude Code are powerful — but they start every session with zero context about your project. You spend the first few minutes re-explaining your architecture, patterns, and conventions. Every time.

A `CLAUDE.md` file helps, but it only scratches the surface and goes stale the moment your code evolves.

## The Solution

AutoDocs gives your coding agent a **structured, queryable knowledge base** about your codebase — and keeps it automatically up to date every time you merge code.

```
autodocs init
    → Claude Code analyzes your codebase
    → Generates a structured MCP docs server
    → Registers the MCP server with Claude Code automatically
    → Writes .claude/CLAUDE.md so Claude self-onboards every session
    → GitHub Action watches for merged PRs
    → Claude Code reads the diff, updates the docs
    → PR opened on docs repo for human review
    → Merge → autodocs sync → MCP server stays current. Forever.
```

---

## Prerequisites

- [Claude Code](https://claude.ai/code) installed and authenticated
- Node.js 18+
- Git

---

## Installation

```bash
npm install -g @kmahler0202/autodocs
```

---

## Quick Start

### 1. Initialize a project

Run this from your project's root directory:

```bash
autodocs init
```

This will:
- Prompt you for a project name and paths
- Scaffold a new MCP documentation server repo
- Copy the GitHub Actions workflow into your main repo
- Launch Claude Code to analyze your codebase and generate initial docs
- Register the MCP server with Claude Code automatically
- Write `.claude/settings.json` to auto-approve MCP tool calls (no more per-call prompts)
- Write `.claude/CLAUDE.md` so Claude onboards itself via the MCP at the start of every session

**That's it for local setup.** Open Claude Code in your project and start working — Claude will automatically read the docs before responding to any task.

### 2. Push your docs repo to GitHub

The docs repo is a separate GitHub repository. After `init` completes:

```bash
cd ../your-project-docs-mcp
git remote add origin https://github.com/YOUR-ORG/YOUR-DOCS-REPO.git
git push -u origin main
```

### 3. Set up GitHub secrets and variables

In your **main repo** → Settings → Secrets and variables → Actions:

**Secrets:**
| Name | Value |
|------|-------|
| `ANTHROPIC_API_KEY` | Your [Anthropic API key](https://console.anthropic.com/settings/keys) |
| `DOCS_REPO_PAT` | A GitHub fine-grained PAT (see below) |

**Variables:**
| Name | Value |
|------|-------|
| `DOCS_REPO` | `your-org/your-docs-repo-name` |

**Creating the PAT:**
Go to [GitHub → Settings → Personal access tokens → Fine-grained tokens](https://github.com/settings/personal-access-tokens/new):
- **Repository access:** Select your docs repo (and your main repo too if it's private)
- **Permissions:** Contents (read+write), Pull requests (read+write)

### 4. Keep docs in sync

Every time a PR merges to your main branch, the GitHub Action updates your docs repo automatically and opens a PR for review. Once you review and merge that PR, pull the changes down to your local MCP servers:

```bash
autodocs sync
```

This `git pull`s and rebuilds every registered docs repo at once. Run it whenever you want to pick up the latest docs.

---

## How the Auto-Update Works

Every time a PR is merged to your main branch:

1. The GitHub Action fires
2. Claude Code reads the full diff
3. Updates the affected doc files in your docs repo
4. Opens a PR on the docs repo for human review

You review the doc PR (takes ~2 minutes), merge it, then run `autodocs sync` — and your MCP server has the latest context.

---

## Importing an Existing Docs Repo

If you already have a docs MCP repo set up, register it without regenerating docs:

```bash
autodocs import
```

This validates the repo, registers it with AutoDocs, registers the MCP server with Claude Code, and writes the `.claude/` setup files — same as `init`, skipping the generation step.

---

## CLI Reference

```
autodocs init                Scaffold a docs repo, generate initial docs, and register the MCP server
autodocs import              Register an existing docs MCP repo with AutoDocs
autodocs start [project]     Build and register the MCP server with Claude Code
autodocs stop [project]      Unregister the MCP server from Claude Code
autodocs sync [project]      Pull the latest docs for all registered MCP servers (or a specific one)
autodocs status              Show registration status for all projects
autodocs list                List all registered projects
autodocs config show         Print the AutoDocs config as JSON
autodocs config remove       Unregister a project from AutoDocs (does not delete files)
```

---

## How the MCP Server Works

The generated docs server exposes five tools to your AI agent:

| Tool | What it does |
|------|-------------|
| `list_architecture` | Returns the full system architecture overview — best starting point |
| `list_modules` | Index of all doc files grouped by category |
| `get_module` | Retrieve full documentation for a specific module |
| `search_docs` | Keyword/phrase search across all docs |
| `get_code_examples` | Find code examples by topic |

---

## Repository Structure

```
autodocs/
├── src/
│   ├── commands/          # CLI commands (init, import, start, stop, sync, status, list, config)
│   ├── utils/             # Shared utilities
│   ├── mcp-registry.ts    # MCP registration, permissions, and CLAUDE.md setup
│   ├── state.ts           # Config management (~/.autodocs/config.json)
│   └── types.ts           # Shared types
├── template/
│   ├── mcp-server/        # MCP server template (copied into docs repo on init)
│   ├── CLAUDE.md          # Instructions for the doc-maintenance Claude agent
│   └── update-mcp-docs.yml # GitHub Actions workflow template
└── src/__tests__/         # Tests
```

---

## Tips for Best Results

**Invest in the initial generation.** The GitHub Action maintains docs — it doesn't create from scratch. A thorough initial Claude Code session pays dividends on every future update.

**Review doc PRs seriously.** The human review step is a feature, not a formality. Claude is good, but it can miss context. Treat doc PR review as a lightweight but meaningful checkpoint.

**Keep your docs repo private if your main repo is private.** The PAT needs access to both in that case.

**Run `autodocs sync` after merging doc PRs.** This pulls the latest changes down to your local MCP servers so Claude has current context immediately.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

---

## License

MIT — see [LICENSE](LICENSE).

---

*Built by [@kmahler0202](https://github.com/kmahler0202) at [The Mx Group](https://www.themxgroup.com)*