# mdgen-mcp

MCP server for [mdgen](https://mdgen.app) — read and write your mdgen documents from
Claude Desktop, Claude Code, Codex CLI, and other MCP clients, using **your own**
account. The AI runs on your subscription; mdgen never pays for generation.

## What it does

Exposes your saved mdgen documents (available to logged-in users) as MCP tools:

| Tool | Description |
|------|-------------|
| `list_documents` | List your documents (id, title, mode, updatedAt) |
| `read_document` | Get a document's full Markdown by id |
| `create_document` | Create a new document (`markdown`, `title?`, `mode?`) |
| `update_document` | Update a document (only provided fields change) |
| `delete_document` | Delete a document by id |

## Prerequisites

1. A mdgen account (sign in at https://mdgen.app).
2. A **personal access token (PAT)**: issue one from mdgen while logged in
   (Menu → API tokens). Copy it — it is shown only once.

## Environment variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `MDGEN_TOKEN` | ✅ | — | Your mdgen personal access token |
| `MDGEN_API_URL` | | `https://api.mdgen.app/v1` | mdgen API base URL (must include the version prefix) |

## Client setup

### Claude Desktop

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mdgen": {
      "command": "npx",
      "args": ["-y", "mdgen-mcp"],
      "env": {
        "MDGEN_TOKEN": "<your token>"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add mdgen --env MDGEN_TOKEN=<your token> -- npx -y mdgen-mcp
```

### Codex CLI

`~/.codex/config.toml`:

```toml
[mcp_servers.mdgen]
command = "npx"
args = ["-y", "mdgen-mcp"]
env = { MDGEN_TOKEN = "<your token>" }
```

## Security

- Your PAT is passed via your client's `env` and never leaves your machine except as a
  `Authorization: Bearer` header to the mdgen API. It is **not** stored in this package.
- The PAT grants access only to **your** documents. Revoke it anytime from mdgen.
- Treat the token like a password. Do not commit it.

## Development

```bash
npm install
npm run dev     # run from source (tsx)
npm run build   # emit dist/
npm test        # unit tests
```

## Publishing

Releases publish to npm via GitHub Actions on `v*` tags, using
[npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers) (OIDC, no token)
with build provenance.

```bash
npm version patch      # bump version + create commit/tag
git push && git push --tags
```

## License

MIT © Shien Inc.

Part of [mdgen](https://mdgen.app).