- Python 92%
- Makefile 4%
- Dockerfile 2.5%
- Shell 1.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .forgejo/workflows | ||
| docsmcp | ||
| plugins/docs-indexer | ||
| scripts | ||
| vski/docs | ||
| .env.example | ||
| .gitignore | ||
| docker-compose.yml | ||
| Dockerfile | ||
| Makefile | ||
| pyproject.toml | ||
| README.md | ||
| run.sh | ||
vski docs MCP
A public MCP server that gives coding agents semantic access to the VSKI documentation and the canonical example repositories. Docs results are canonical links (docs.vski.ai pages and the raw markdown on vski.sh); example code and code comments are served in full, straight from the canonical repos.
It is built the platform way, and doubles as a reference project for a plugin + pipeline + cron + IaC deployment on a single image:
flowchart LR
subgraph image ["one image, one container"]
subgraph vski ["headless vski server"]
P["docs-indexer plugin<br/>(warm, python)"]
C["collections + vectors<br/>+ graph kb"]
end
M["MCP server<br/>(Streamable HTTP)"]
end
CI["CI workflows<br/>(deploy, converge)"]
CR["cron<br/>every 6h"] -->|"pipeline://docs-reindex"| PL["pipeline<br/>docs-reindex"]
PL -->|"plugin step"| P
W["wiki + canonical repos<br/>(cloned from vski.sh)"] --> P
A["coding agents"] -->|"MCP tools"| M
M -->|"reads"| C
CI -.->|"ships + converges"| image
style image fill:#f5f5f5,stroke:#999
How it works
- The indexer is a plugin (
plugins/docs-indexer/, code indocsmcp/plugin.py). Thedocs-reindexpipeline (IaCvski/docs/pipelines.yaml) invokesdocs-indexer/index_all, and a cron entry (vski/docs/cron.yaml) kicks that pipeline every six hours. The Bootstrap workflow kicks it once right after the IaC apply so a fresh deployment serves immediately. All writes go through the plugin's role-scoped key ('plugin' in @request.auth.rolesrules on every collection). - Docs are links, not copies. Pages and sections are indexed for search
but stored as canonical URLs only:
https://docs.vski.ai/<page>/and the raw markdown athttps://vski.sh/x/platform/wiki/raw/{Page}.md. Agents fetch the markdown themselves; this service never re-serves doc content. - Only canonical repos are indexed, discovered from the docs themselves.
The indexer scans the wiki for
vski.sh/x/{repo}references and indexes exactly those (server sources excluded). Every file becomes a searchable record, and every substantial comment block or docstring becomes one too, because comments carry the usage patterns agents search for. - One Dockerfile, two processes, no deployment logic inside. The image
runs the headless vski server (with the plugin enabled; the reconcile loop
starts enabled instances) and the MCP server on the platform port, which
authenticates with
VSKI_API_KEYfrom the environment. Two CI workflows own everything else: Deploy ships the image (dokku app, volume, ports, config), Bootstrap converges the deployment state through the vski CLI (vski admins ensure,vski iac apply vski, one index kick). CI holds API keys minted in the deployment, never admin logins; nothing is created or applied inside the container. - Embeddings are one OpenAI-compatible client (
POST {base}/embeddingswith a bearer token), and the API key is IaC all the way.vski/docs/secrets.yamldeclaresembedApiKeywithfromEnv(theEMBED_API_KEYrepo secret in CI,.envlocally);iac applystores it encrypted, thedocs-reindexstep resolves{{secrets.embedApiKey}}and hands it to the plugin as itsapiKeyparam, and the MCP server gets query vectors by invoking the plugin'sembedfunction. The key never sits in YAML, container environment, or the MCP process. Endpoint and model come from the plugin instance config (Gemini's OpenAI-compatible endpoint by default; any provider works, Ollama's/v1locally), and the model must match between indexing and queries.
Tools
| Tool | What it returns |
|---|---|
search_docs(query, limit) |
Ranked pages: canonical page URL + raw-markdown URL + matching section anchor, with related pages/repos from the kb graph attached. Links only. |
list_docs() |
Every indexed page and example repo, as links. |
search_code(query, language?, kind?) |
Example files and comments by meaning; kind: "comment" searches the mined comments. |
get_example(repo, path) |
Full source of one example file with its vski.sh URL. |
index_status() |
Latest indexer runs: counts, indexed repos, skips, errors. |
Run locally
cp .env.example .env
make up # build the image, start the container
make setup # create the local admin, mint VSKI_API_KEY, recreate
make iac-apply # apply the IaC with the vski CLI (db, plugin, pipeline, cron)
make reindex # run one docs-reindex pass now
make runs # watch the run; make status for the indexer summary
make search q='how do triggers work'
The MCP endpoint is http://127.0.0.1:9380/mcp; the headless vski API
(dashboards connect here) is http://127.0.0.1:3110. The same CLI targets
work against any deployment: make iac-apply IAC_URL=https://docs-mcp.example.
Local development mounts the wiki checkout (DOCMCP_WIKI_PATH) so unpushed
edits are indexed; repos are cloned from vski.sh exactly as in production.
The compose file overrides the embeddings endpoint and model to local
Ollama; drop those two lines to exercise the production defaults from
plugins.yaml. The API key is not environment anywhere: make iac-apply
stores it as the embedApiKey pipeline secret from .env.
Deployment
One workflow ships this service in two stages
(.forgejo/workflows/deploy.yml), running unchanged on GitHub Actions
and Forgejo Actions (only runs-on differs).
The general pattern (secrets taxonomy, first-deployment runbook, dokku
and k8s specifics) is documented once in the platform reference:
CI/CD. What follows is specific to this
repository.
- Deploy (
deploy.yml, push to main): dokku appmcp, persistent volume at/app/data, TLS port maps (https://mcp.vski.aifor the MCP endpoint,https://mcp.vski.ai:3110for the headless vski API that dashboards connect to),JWT_SECRETfrom the repo secrets, image build viagit:sync --build-if-changes. The deployment spec is the workflowenvblock (APP_NAME,APP_DOMAIN,VSKI_HOST_PORT). - Bootstrap (a second job,
needs: deploy, in a python image):vski health --wait,vski admins ensure(first admin, repo secrets),vski iac apply vski --yes(db, collections, kb graph, plugin, pipeline, cron, theembedApiKeysecret), then onevski pipelines run docs-reindexkick so a fresh deploy serves immediately instead of waiting for the cron tick (the run waits for the index to finish and reports the counters as its output).
Repository secrets: VSKI_URL (https://mcp.vski.ai:3110),
ADMIN_EMAIL / ADMIN_PASSWORD (used only while no admin exists),
JWT_SECRET, EMBED_API_KEY (stored by apply as the embedApiKey
pipeline secret), CI_API_KEY (the admin key; the bootstrap job
authenticates with it and the deploy job writes it into the app config as
the MCP server's VSKI_API_KEY, so one key minted once serves both).
SQLite keeps the deployment to one container with one volume on one host;
never scale web past one.
Repository layout
docsmcp/ providers (OpenAI-compatible embeddings), wiki + repo
parsing, indexing core, plugin (index_all), MCP server
scripts/ setup (local admin + key), search (CLI debug queries)
plugins/docs-indexer/ plugin manifest (vplugin.yaml)
vski/docs/ IaC: database, collections, kb graph, plugin instance,
docs-reindex pipeline, cron schedule, embedApiKey secret
.forgejo/workflows/ Deploy (dokku app, volume, ports, JWT) and
Bootstrap (admins, IaC apply incl. secrets, index kick)
Dockerfile the single deployment image (headless vski + MCP)
run.sh process supervisor (server + MCP server)
Operating notes
- Indexing is incremental (content hashes); unchanged pages and files cost nothing and consume no embedding quota.
- A docs-reindex run reports the real outcome: the
indexstep acks fast and the run waits on the plugin'sindex-donesignal; when the pass lands, thereportstep completes the run with the counters as its output or fails it if the pass failed. Monitor withvski runs list --db docs/vski runs show <runId> --db docs, the dashboard,vski plugins instances logs docs-indexer --db docs, or the MCPindex_statustool (the same history lives in theindex_runscollection). The signal path needs a server newer than v0.15.0 (plugin keys carry theworkflowsrole); on older servers the run waits forever after the ack. - If the plugin process dies mid-pass, the waiting run never gets its
signal; cancel it and let the next cron kick (or a manual
vski pipelines run docs-reindex) redo the pass. - The embeddings model used at index time must also serve queries (same vector space); switching means wiping the data volume and reindexing.
- The docs index never stores doc content, so rewrites on the wiki propagate on the next index run with nothing to clean up here.