gnosis-mcp
docs · graph · skills
skills

Status

skills/status/SKILL.md

Status

Diagnostic for "something is wrong with gnosis-mcp". Produces a compact report the user can screenshot and paste in an issue.

Usage

/gnosis:status              # Full check — connectivity + schema + stats + common failure modes
/gnosis:status quick        # Just connectivity
/gnosis:status stats        # Document / chunk / embedding counts
/gnosis:status diag         # Extended diagnostics (used when something is wrong)

Mode: $ARGUMENTS

Step 1 — connectivity

Preferred path: the MCP itself. If mcp__gnosis__* tools respond, the server is up and MCP is wired correctly.

mcp__gnosis__get_graph_stats()

If that returns data, skip to Step 2.

MCP tool not available

Two common causes:

  1. Server not running — for stdio transport, the MCP client should auto-spawn the server. If not: check .mcp.json / .claude/mcp.json config, confirm gnosis-mcp is on PATH.
  2. Server running, but client not connected — restart the editor once MCP config is correct.

Direct CLI check (works independent of MCP wiring):

gnosis-mcp check

Expected output:

Backend: sqlite (SQLite 3.46.0)
Database: /home/<you>/.local/share/gnosis-mcp/docs.db
chunks_table_exists: true (1742 rows)
fts_table_exists:    true
sqlite_vec:          true
vec_table_exists:    true (1742 rows)
links_table_exists:  true (812 rows)
embeddings_coverage: 100.0%

If check itself returns errors, stop here — the server can't talk to its own database. Likely causes:

  • DB file doesn't exist → gnosis-mcp init-db
  • DB schema old → gnosis-mcp init-db (idempotent, adds any new columns)
  • SQLite extension missing (sqlite_vec: false) → pip install 'gnosis-mcp[embeddings]'

Step 2 — corpus stats

mcp__gnosis__get_graph_stats()

Report in a compact block:

Docs:       412
Chunks:     1,247   (avg 3.0 per doc at current chunk_size)
Orphans:    18      (docs with no graph edges)
Top hubs:
  README.md        37 links
  docs/tools.md    24 links
  docs/config.md   19 links

Edge types:
  related           612
  content_link      410
  git_co_change     225

Reading the signal

  • 0 docs: nothing indexed — tell the user to gnosis-mcp ingest ./docs
  • docs > 0 but chunks == 0: schema drift; gnosis-mcp init-db followed by a re-ingest
  • avg chunks per doc > 15: either your chunk size is too small (default is 2000 chars; check GNOSIS_MCP_CHUNK_SIZE) or your docs are huge
  • orphans > 40 % of total: graph is flat; users aren't using relates_to: frontmatter or [markdown](links.md)
  • edge distribution heavily git_co_change: the curated knowledge is thin; git ingest is dominating. Consider pruning git history with --since 3m or removing ingest-git

Step 3 — embeddings

gnosis-mcp stats

Look for:

Chunks with NULL embeddings: 0  ✓

If non-zero, embeddings are partial. Fix:

gnosis-mcp embed       # backfill the missing ones

If that command errors about a missing provider, the user doesn't have the [embeddings] extra installed:

pip install 'gnosis-mcp[embeddings]'

Step 4 — reranker (only if diag mode or user reports slow search)

python -c "from gnosis_mcp.rerank import get_reranker; get_reranker().score('test', ['test passage'])"

Failure modes:

  • ImportError → [reranking] extra not installed
  • HTTPError 401/404 on model download → model URL stale. If the default model returns 401, override: GNOSIS_MCP_RERANK_MODEL=cross-encoder/ms-marco-MiniLM-L6-v2
  • First call takes 60+ s → model download in progress (check ~/.local/share/gnosis-mcp/rerankers/)

Reminder for users enabling reranking: our measurements show MS-MARCO-class rerankers hurt dev-doc retrieval by ~27 nDCG@10. Disable unless /gnosis:tune full confirms it helps on the user's specific corpus.

Step 5 — server transport (HTTP deployments only)

If the server runs as streamable-HTTP (not stdio):

curl -fsS http://127.0.0.1:8000/health | jq .

Expected:

{
  "status": "ok",
  "version": "0.11.0",
  "docs": 412,
  "chunks": 1247,
  "backend": "sqlite"
}

Common failures:

  • Connection refused → server isn't running
  • 401 → GNOSIS_MCP_API_KEY is set but the probe didn't send a Bearer token. Note: /health is always public; 401 there suggests an unusual reverse-proxy config
  • 500 → check server logs (journalctl -u gnosis-mcp -f or docker logs gnosis-mcp)

Step 6 — access log (diag mode)

If users complain about stale "most popular" results from get_context:

-- in the SQLite DB:
SELECT count(*) FROM search_access_log WHERE timestamp > datetime('now', '-30 days');
  • Zero rows and GNOSIS_MCP_ACCESS_LOG=false → logging disabled by config (intentional for privacy-sensitive deployments)
  • Zero rows and logging enabled → search_docs + get_doc haven't been called yet; expected on a fresh install

Purge old rows with gnosis-mcp cleanup --days 30 (weekly cron).

Quick mode

Just steps 1 and 2. Skip embeddings/reranker/transport checks.

Connectivity: ✓
Docs:         412 / Chunks: 1,247

Full report format

Always include these fields when giving the user a status summary:

## gnosis-mcp status

Server:       running (stdio | streamable-http) · v0.11.0
Backend:      sqlite / postgres
DB path:      ~/.local/share/gnosis-mcp/docs.db
Schema:       current ✓
Docs:         412
Chunks:       1,247 (avg 3.0/doc)
Embeddings:   1,247 / 1,247 (100 %)
Chunk size:   2000 chars (v0.11 default)
Writable:     false  (set GNOSIS_MCP_WRITABLE=true to enable upserts)
Reranker:     disabled  (recommended on dev docs)
Access log:   enabled, 1,289 entries in last 30 days

Known issues: none   OR   <list each found>
Recommended:  <one-line next action>

See also

  • /gnosis:setup — first-time setup wizard
  • /gnosis:ingest — populate / re-populate / prune the corpus
  • /gnosis:tune — find the chunk size / retrieval config optimum
  • Troubleshooting guide for every known error message