No description
  • Python 92%
  • Makefile 4%
  • Dockerfile 2.5%
  • Shell 1.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Anton Nesterov ece0e54760
All checks were successful
Deploy / deploy (push) Successful in 1m49s
Deploy / bootstrap (push) Successful in 23s
small bugfix
2026-11-05 15:14:18 +01:00
.forgejo/workflows test 2026-11-03 20:57:45 +01:00
docsmcp small bugfix 2026-11-05 15:14:18 +01:00
plugins/docs-indexer improve monitoring 2026-11-03 22:35:21 +01:00
scripts test 2026-11-03 19:52:34 +01:00
vski/docs improve indexing 2026-11-05 14:15:09 +01:00
.env.example test 2026-11-03 19:52:34 +01:00
.gitignore test 2026-11-03 19:52:34 +01:00
docker-compose.yml test 2026-11-03 19:52:34 +01:00
Dockerfile improve monitoring 2026-11-03 22:35:21 +01:00
Makefile test 2026-11-03 19:52:34 +01:00
pyproject.toml test 2026-11-03 19:19:06 +01:00
README.md improve monitoring 2026-11-03 22:35:21 +01:00
run.sh test 2026-11-03 19:19:06 +01:00

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 in docsmcp/plugin.py). The docs-reindex pipeline (IaC vski/docs/pipelines.yaml) invokes docs-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.roles rules 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 at https://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_KEY from 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}/embeddings with a bearer token), and the API key is IaC all the way. vski/docs/secrets.yaml declares embedApiKey with fromEnv (the EMBED_API_KEY repo secret in CI, .env locally); iac apply stores it encrypted, the docs-reindex step resolves {{secrets.embedApiKey}} and hands it to the plugin as its apiKey param, and the MCP server gets query vectors by invoking the plugin's embed function. 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 /v1 locally), 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 app mcp, persistent volume at /app/data, TLS port maps (https://mcp.vski.ai for the MCP endpoint, https://mcp.vski.ai:3110 for the headless vski API that dashboards connect to), JWT_SECRET from the repo secrets, image build via git:sync --build-if-changes. The deployment spec is the workflow env block (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, the embedApiKey secret), then one vski pipelines run docs-reindex kick 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 index step acks fast and the run waits on the plugin's index-done signal; when the pass lands, the report step completes the run with the counters as its output or fails it if the pass failed. Monitor with vski runs list --db docs / vski runs show <runId> --db docs, the dashboard, vski plugins instances logs docs-indexer --db docs, or the MCP index_status tool (the same history lives in the index_runs collection). The signal path needs a server newer than v0.15.0 (plugin keys carry the workflows role); 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.