Helpdock MCP Server
Officialby 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
```
[](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._
[](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`.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues