Skip to main content
Glama
Helpdock MCP Server

Helpdock MCP Server

Official
by flisk-sh
README.md
# Helpdock

**Any GitHub repo's docs, as a help center and an MCP server.** Replace `github.com` with `helpdock.flisk.si`:

```
https://github.com/vercel/next.js  →  https://helpdock.flisk.si/vercel/next.js
```

[![How Helpdock works: replace github.com with helpdock.flisk.si, browse the docs, get answers quoted from the exact page, and add the docs to your AI over MCP](docs/demo.gif)](https://helpdock.flisk.si)

- **A help center for any public repo.** Ask in your own words; answers are passages quoted from the docs (whole paragraphs and code blocks, not fragments), each linked to its file and heading on GitHub. Every page is browsable.
- **An MCP server per repo.** `https://helpdock.flisk.si/owner/repo/mcp` gives Claude, ChatGPT, Cursor or Codex that repo's docs: `search_docs` and `ask_help_center`, read-only, no key.
- **Your AI, not ours.** Helpdock never calls a model. Under every answer, *Ask your AI* hands the question and the cited passages to the visitor's own ChatGPT or Claude.
- **No signup, no database, no API key.** The URL is the state. A repo is read on its first visit (one GitHub API call lists it, the Markdown is fetched in parallel; GitHub's archive is the fallback when the API limit is used up), listed again when its branch moves: a visit checks the head commit with `git ls-remote` at most every three minutes (not an API call), so a push shows within minutes. Opening a repo costs almost no memory: the table of contents is a list of file paths and every page is fetched from GitHub when you open it. The SQLite full-text index is built for a repository only when someone asks it a question (a few seconds) and dropped after ten idle minutes. An optional `GITHUB_TOKEN` (read-only, public repositories) raises GitHub's limit from 60 to 5000 calls an hour.
- **A folder of a repository, too.** Paste a GitHub folder link and only that folder opens: `helpdock.flisk.si/hashicorp/web-unified-docs/tree/main/content/terraform/v1.17.x/docs` is the Terraform docs, with the same MCP server at its `/mcp`.
- **Markdown, MDX and reStructuredText.** Django's docs (`docs/*.txt`) and any Sphinx `.rst` are converted to Markdown first: titles, code blocks, notes, signatures and cross-references. HashiCorp's MDX callouts and Docusaurus-style MDX work too.
- **Or your own docs.** Without `HELPDOCK_REPOS`, `/` is a help center for your own Markdown (`seed-docs/`, `POST /docs`), on SQLite or your own Postgres. Built and run with [Flisk](https://github.com/flisk-sh/flisk).

## Run it

Needs Docker, Tilt and the [Flisk CLI](https://github.com/flisk-sh/flisk).

```bash
git clone https://github.com/flisk-sh/helpdock.git
cd helpdock
flisk project --yes
flisk up agents
flisk status          # the agent URL, e.g. http://api.helpdock.localhost:8082/api/agent
```

Open the agent URL with a trailing slash in a browser. The first start loads the starter pages (seven pages of the Flisk docs, from `services/agents/agent/seed-docs/`) into the `help_docs` table.

Use your own docs: replace the files in `seed-docs/` and run `bun run seed:pack` in `services/agents/agent` before the first start (the image ships only compiled code, so the pages are packed into `src/seed-docs.generated.ts`). Or add pages at any time:

```bash
curl -s -X POST "$AGENT_URL/docs" -H 'content-type: application/json' \
  -d "$(jq -n --arg m "$(cat billing.md)" '{source:"billing.md", markdown:$m}')"
```

## Choose what your repository's help center shows

Helpdock finds the Markdown in a repository by itself, and leaves out what is not documentation for readers: dependencies, fixtures, change logs, release notes, translations (`docs/de/…`, `README-de.md`, `intro.ja.md`) and `drafts/` folders. Links between pages stay in Helpdock.

To choose the pages and their order yourself, add a `.helpdock.json` at the top of the help center's folder: the folder of a `/tree/<branch>/<folder>` link (`docs/.helpdock.json` for `helpdock.flisk.si/owner/repo/tree/main/docs`), or the repository root.

```json
{
  "include": ["**"],
  "exclude": ["internal/**", "benchmarks/results/**"],
  "groups": [
    { "name": "Get started", "pages": ["quickstart.md", "install/*.md"] },
    { "name": "Guides", "pages": ["guides/**"] },
    { "name": "Reference", "pages": ["reference/**", "cli.md"] }
  ],
  "start": ["quickstart.md", "guides/ci.md"],
  "questions": ["Do we need Kubernetes?", "How do I use it in CI?"]
}
```

| Key | What it does |
| --- | --- |
| `include` | Globs of the pages to show. Without it, every page Helpdock finds. |
| `exclude` | Globs of pages to leave out of the page list, the search index and the MCP server. |
| `groups` | The sections of the page list, in this order. A page goes to the first group with a glob that matches it, and is placed by the first glob it matches, then by path. Pages in no group come after the groups, under *More*. |
| `start` | The *Start here* cards, in order (up to 12; six are shown). Without it, the first group's first six pages. |
| `questions` | The questions offered under the question box and typed as its placeholder, in order (up to 60 of at most 120 characters; eight are shown, the rest behind "More questions", and all are suggested while typing). Without it, the *Start here* pages' titles. |

Every key is optional. Paths and globs are relative to that folder: `*` matches within one folder, `**` across folders, and a folder name means everything in it. Helpdock reads the file each time it lists the repository (on the first visit after a push, checked at most every three minutes, or after a restart); a missing or broken file means the defaults above.

## Online

Helpdock runs online for free at **helpdock.flisk.si** on one Render free web service (from [`render.yaml`](render.yaml) and the root [`Dockerfile`](Dockerfile)), with no database account and no AI key: without `DATABASE_URL` it uses Bun's built-in SQLite. Bring your own Postgres (Neon or any other) to keep added pages and history. [DEPLOY.md](DEPLOY.md) has the steps, the DNS record, the limits and what free costs you (the service sleeps after 15 idle minutes).

## API

| Route | What it does |
| --- | --- |
| `GET /` | The help center page |
| `POST /turn` | `{"input": "question"}` with an `x-session-id` header → `{reply, sources, prompt}` (`prompt` is what *Ask your AI* hands over); the session is checkpointed in Postgres |
| `POST /mcp` | Public read-only MCP (Streamable HTTP): `search_docs`, `ask_help_center` |
| `GET /status`, `/pages`, `/page?source=` | The help center's state, its page list, one page's sections |
| `/owner/repo/…` | With `HELPDOCK_REPOS=1`: all of the above for a public GitHub repository (`/owner/repo/turn`, `/owner/repo/mcp`, …) |
| `GET /search?q=` | Ranked sections with snippets; each hit has `url` (the file on GitHub) and `page` (the same page in Helpdock) |
| `POST /docs` | `{"source", "markdown"}` adds or replaces one page; needs `authorization: Bearer $HELPDOCK_ADMIN_TOKEN` when the token is set, and is off in production without it |

The read-only routes (`/status`, `/pages`, `/page`, `/search`, `/lead`, `/readme`) send `access-control-allow-origin: *`, so another site can show a repository's pages from the browser. `/mcp` allows it too; `/turn`, `/session` and `/docs` do not.

Settings: `HELPDOCK_DOCS_DIR`, `HELPDOCK_REPOS`, `HELPDOCK_PREWARM`, `HELPDOCK_REPO_BUILDS_PER_HOUR`, `GITHUB_TOKEN` (optional: raises GitHub's 60 API calls an hour), and for online use `HELPDOCK_ADMIN_TOKEN`, `HELPDOCK_PROXY`, `HELPDOCK_TURNS_PER_HOUR`, `HELPDOCK_PUBLIC_URL` (see the header of `services/agents/agent/src/index.ts`).

---

_Helpdock started from the Flisk agent-stack template. Its notes follow._


[![Uses Flisk CLI](https://img.shields.io/badge/Uses-Flisk%20CLI-blue?style=flat-square&logo=github)](https://github.com/flisk-sh/flisk)

Starter landscape for AI agents on Flisk: a Bun agent resource, an MCP tool server, Postgres, and NATS.

## Prerequisites

- Docker running
- Tilt installed
- Bun installed
- [Flisk CLI](https://github.com/flisk-sh/flisk)

## Quick start


> **Repository-pinned CLI (optional):** Run `bun install` from the repository root to install the version pinned in `package.json`. Use `bun run flisk:project` to initialize project config, `bun run flisk:dry-run` to preview startup, or `bun run flisk:up -- <stack>` to start a stack. The global npm and standalone binary installation paths remain available.

```bash
git clone https://github.com/flisk-sh/flisk-agent-stack.git
cd flisk-agent-stack
flisk project --yes
flisk up
```

Or from the CLI:

```bash
flisk project agent-stack
cd flisk-agent-stack
flisk up
```

## Landscape

| Stack   | Resource        | Type     | Notes                                                                 |
|---------|-----------------|----------|-----------------------------------------------------------------------|
| agents  | agent-migrator  | migrator | Creates the `flisk_agent_sessions` table once, before the agent starts |
| agents  | agent           | agent    | Custom runtime, `durability: postgres`: each turn is checkpointed in Postgres |
| agents  | tools           | mcp      | MCP tool server (Streamable HTTP at `/mcp`), one `echo` tool to replace |
| agents  | postgres        | database | Checkpoint store (`services/platform/database-management`)            |
| agents  | nats            | broker   | Messaging (`services/platform/messaging`), for agents that queue work |

## Try the agent

Once `flisk up agents` is running, find the agent's URL with `flisk networks` and send turns with the `x-session-id` header. Each session keeps its transcript in Postgres, so it survives a restart of the agent:

```bash
AGENT_URL=<the agent URL from flisk networks>
curl -s -X POST -H 'x-session-id: demo' -H 'content-type: application/json' -d '{"input":"hello"}' "$AGENT_URL/turn"
curl -s -H 'x-session-id: demo' "$AGENT_URL/session"
```

`/ready` answers 503 while the checkpoint store is unreachable. The replacement for the placeholder turn lives in `runTurn` in [`services/agents/agent/src/index.ts`](services/agents/agent/src/index.ts).

Scaffold more with:

```bash
flisk resource my-agent --type agent --stack agents --durability files
flisk resource my-tools --type mcp --stack agents
```

See [flisk](https://github.com/flisk-sh/flisk) and the website [llms.txt](https://flisk.sh/llms.txt) for the full contract.

The film on the landing page and above is made by [`video/`](video/): `bun video/shots.ts` takes screenshots of the live site, `bun video/render.ts` films them in headless Chrome (needs Chrome and ffmpeg). Scenes are in `video/film.json`.