version: "1.0.0" name: status description: Verify gnosis-mcp server connectivity, schema integrity, and corpus health. Use when MCP calls fail, return empty, or return unexpected data.

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 the client's MCP config (.mcp.json for Claude Code, .cursor/mcp.json for Cursor, and so on), confirm gnosis-mcp is on PATH.

1. 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