Allows searching arXiv papers and ingesting them into the knowledge graph, with an explainer skill for paper summaries.
Enables scanning Confluence pages and integrating them as nodes in the knowledge graph.
Facilitates scanning GitHub repositories and linking them as nodes, with author resolution and homepage extraction.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mindgap find nodes about 'deep learning'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Give an agent a goal and a place to remember. It loops — reading what's known, researching, writing back evidence-linked findings — and a knowledge graph grows itself across sessions. mindgap is that memory: a local, org-roam-style graph for research and project knowledge (concepts, definitions, software, repos, Confluence pages, arXiv papers, people, teams) that autonomous loop sessions read before they work and write after — markdown nodes densified with [[wiki-links]], every node carrying its source URLs, rendered live in 2D/3D. You can hand-curate via CLI + web UI too; the agents just never stop adding.
"LLMs are exceptionally good at looping until they meet specific goals. Don't tell it what to do — give it success criteria and watch it go." — Andrej Karpathy
An agent looping toward a goal needs somewhere to look before it starts and somewhere to put what it finds. mindgap is that somewhere. Each session reads the relevant subgraph for context, does the work — sweep arXiv, map a repo, mine the connections for buildable ideas — then ingests new nodes and edges with provenance. Nothing evaporates when the context window closes: the next run builds on the last, and knowledge compounds instead of being re-derived. You supply the goal and the success criteria; the graph is the durable, queryable memory the loop reads and writes.
Related MCP server: markdown-vault-mcp
pipx install git+https://github.com/grburgess/mindgap.git
mindgap init # create ~/.mindgap/mindgap.db + a small demo graph
mindgap serve # open the web UI at http://localhost:8765The seeded graph is just a demo to show the shape. To start your own, clear it — the database recreates itself empty on next use:
rm ~/.mindgap/mindgap.db
mindgap add --title "My first concept" --tags research # then grow it via the CLI, the web UI, or MCP(Don't re-run mindgap init after clearing — that re-seeds the demo. Or point MINDGAP_DB at a new path to keep the demo and start a separate graph.)
Stdlib-only Python 3.10 — no pip installs. Data lives in a single SQLite file.
Pick one. All paths put mindgap (and mindgap-mcp) on your PATH and store data in
~/.mindgap (override with MINDGAP_HOME, or MINDGAP_DB for just the DB file).
pipx (recommended): pipx install git+https://github.com/grburgess/mindgap.git mindgap init # creates ~/.mindgap/mindgap.db and seeds it mindgap serve # web UI at http://localhost:8765
pip: pip install --user git+https://github.com/grburgess/mindgap.git mindgap init && mindgap serve # ensure ~/.local/bin is on PATH
From a clone (no install / development): git clone https://github.com/grburgess/mindgap.git && cd mindgap ./install.sh # self-locating: PATH + ~/.mindgap + seed mindgap serve
/plugin marketplace add grburgess/mindgap
/plugin install mindgap
Registers the mindgap MCP server and the paper-to-mindmap, arxiv-explainer, papers-library, and loop-system skills.
Register the MCP at user scope so every Claude Code session, in any directory, can reach the graph:
claude mcp add -s user mindgap mindgap-mcp # global; needs mindgap-mcp on PATH-s user is what makes it global (the default scope is local/current-dir only). The launcher self-locates and the DB lives in ~/.mindgap, so it runs from anywhere. A source checkout also ships a project-scoped .mcp.json → ./bin/mindgap-mcp, active only inside this repo.
~/.mindgap/ — mindgap.db and snapshots/. MINDGAP_HOME relocates the whole dir;
MINDGAP_DB points at a single DB file elsewhere.
You don't drive this graph node-by-node — you point an agent at a goal and let it loop. Install the Claude Code plugin, then in any project just say:
"set up an arxiv-weekly loop watching <your topics> and run the first pass"
"continue the <name> loop"
"ideate buildable implementations from my <name> graph, and refute the ones that aren't feasible"
"build a graph of the authors doing <your topics> work, with their github pages"Every run follows the protocol in AGENTS.md — read the existing subgraph for context, research, then ingest new nodes/edges with provenance and [[wiki-links]], and export a snapshot. The agent reaches the graph through the MCP server (validated writes that can't silently desync) or the CLI below. Beyond loops, every Claude Code session can deposit what it learned automatically. Then watch it compound — and re-run the loop tomorrow to grow it further. The pieces:
Agent loops — give a goal (a topic, a library, a question); the loop runs to it and writes findings back, self-tuning each pass.
MCP server — the read/write interface agents use, with guardrails (no partial commits, no dangling edges, provenance required).
Self-learning capture — a SessionEnd hook that distills on-domain learnings from any session into the graph, unattended.
mindgap add --title T [--id ID] [--type TYPE] [--body MD | --body-file F]
[--tags a,b] [--url KIND=URL ...] [--by AGENT]
mindgap link SRC DST [--rel REL] [--weight W] [--by AGENT]
mindgap ingest FILE|- # bulk JSON ('-' = stdin)
mindgap find QUERY [--type T] [--tag T] [--json]
mindgap show ID [--json] # node + neighbors + urls
mindgap context QUERY [--depth 1] # markdown digest (for agents)
mindgap rm ID
mindgap unlink SRC DST [--rel REL]
mindgap export [--out FILE] # JSON snapshot -> ~/.mindgap/snapshots/
mindgap stats
mindgap lint [--json] # graph health: orphans/stubs/dups/stale
mindgap serve [--port 8765] [--no-open]mindgap serve opens a single-page graph viewer (dark editorial theme), in 2D or 3D:
Force layout that spreads out instead of clumping — charge repulsion, a per-node collision force (2D), and tuned link distance keep nodes from overlapping, and the view auto-fits whenever the layout settles. Nodes are colored by type and sized by degree; hover a link to see its rel.
Settings drawer (gear, top of the header) for live tuning, persisted to localStorage: a dark-theme picker (Editorial, Midnight, Graphite, Aubergine, Carbon), repulsion, link distance and strength, collision, link opacity, arrows, label mode, and the cluster controls below. "Reset to defaults" restores everything.
Cluster feedback. Idea-communities are detected with multi-level Louvain — client-side, deterministic, no extra endpoint. Switch node coloring from type to community to surface them; in 2D each community gets a translucent hull and a centroid label, and in 3D each community gets a glowing nebula orb, with its topic name shown when you hover the orb. A legend (bottom-left) lists every community with its size — click one to isolate it and dim the rest. A Topic repulsion toggle adds a cohesion force that pulls each community toward its own centroid, so topics settle into spatially separate regions (works in 2D and 3D).
Labels in four modes (off / hover / hubs / always). In hubs mode the most-connected nodes stay labelled and the rest fade in as you zoom into a region (2D); 3D shows a name on hover. Topic (community) names appear when hovering a 3D topic orb.
Star field (3D). A subtle, twinkling star field sits behind the 3D scene (toggle in settings). It lives in world space, so orbiting and zooming give real depth parallax — the graph becomes a galaxy you drift through.
Search box and type/tag filter chips narrow the graph live; a stats line sits in the header.
Click a node → sidebar with its markdown body (wiki-links are clickable), tags, outbound URLs (open Confluence/GitHub/arXiv in a new tab), and neighbors. Edit body/tags/urls, link to another node via a search picker, or delete — all inline.
Focus mode (double-click a node) shows its local 1-hop graph; clicking nodes, wiki-links, or neighbors while focused spreads the view ring by ring (org-roam style), and Esc or "unfocus" resets. Selecting any node flies the camera to it and highlights its neighborhood.
Timeline (clock toggle in the header) opens a bottom strip: a per-day histogram of when nodes were added, a draggable playhead + ▶ play that grows the graph over time, and a color by recency / provenance toggle. Backlinks — the sidebar shows linked mentions plus unlinked mentions (nodes whose text names this one) with a one-click link. Quick switcher (Cmd/Ctrl-O) fuzzy-jumps to any node. Orphans chip filters to disconnected nodes.
The UI is vanilla JS with no build step, drawing force-graph/3d-force-graph, d3, marked, and dompurify from CDNs. Community detection and hull geometry live in web/cluster.js; the 3D topic glow (nebula orbs + orb-hover labels) and the twinkling parallax star field live in web/glow3d.js and web/starfield.js, which build sprites/points in the live Three.js scene using a version-pinned three ESM import (esm.sh/three@0.179) exposed as a global.
Topic clusters (2D). Color nodes by community, then flip on Topic repulsion — a cohesion force pulls each topic into its own region.
3D mode. The same graph in three dimensions — drag to orbit, scroll to zoom. A twinkling, world-space star field sits behind the scene, so the graph reads as a galaxy you drift through.
Dark themes. Five built-in dark themes — Editorial, Midnight, Graphite, Aubergine, Carbon — switched live.
Timeline. Scrub the playhead or hit ▶ to watch the graph grow over time — at day / week / month resolution, with a before / after toggle to show only what existed then or only what's new since.
Quick switcher. Cmd/Ctrl-O to fuzzy-jump to any node by title.
For agents, mindgap/mcp.py exposes the graph as an MCP server over stdio — stdlib-only (newline-delimited JSON-RPC 2.0, no pip deps). For all sessions everywhere, register it globally at user scope: claude mcp add -s user mindgap mindgap-mcp (needs mindgap-mcp on PATH; the launcher self-locates and the DB lives in ~/.mindgap, so it works from any directory). A source checkout also ships a project-scoped .mcp.json → ./bin/mindgap-mcp, active only inside the repo.
Ten tools wrap the same db layer as the CLI: mindgap_ingest (batch write), mindgap_add_node, mindgap_link, mindgap_unlink, mindgap_get_node, mindgap_find, mindgap_context, mindgap_stats, mindgap_export, mindgap_remove_node. Unlike the raw CLI, the write tools validate at the call boundary — mindgap_ingest rejects the whole payload (no partial commit) if any edge endpoint isn't in the DB or the payload, mindgap_link refuses to auto-stub a missing endpoint, created_by is required, and writes return the persisted rows so a caller can't claim a write that didn't land.
The graph is designed to be fed by recurring autonomous sessions that scan Confluence, GitHub, and arXiv. The protocol — read context first, ingest JSON with provenance (created_by, source URLs), wiki-link into the existing graph, export at session end — is defined in AGENTS.md. Sessions can drive the graph via the CLI or the MCP tools above (the MCP's validation makes it the safer path for unattended writes).
Disabled by default. mindgap ships the capture engine off, with an empty domain. Nothing fires until you opt in.
Optionally, mindgap can learn from every Claude Code session: a SessionEnd hook runs a cheap deterministic pre-gate (no LLM) and, only when a session looks on-domain, fire-and-forgets a detached headless subagent that distills durable learnings and ingests them — following the knowledge-capture skill and AGENTS.md. Captured nodes carry created_by="capture:<repo>", confidence=0.6, and a urls entry pointing at the transcript, so they sit below hand-curated nodes and are trivially reversible.
To enable it:
mindgap init once — copies the packaged preset to ~/.mindgap/capture.json.
Edit ~/.mindgap/capture.json: set "enabled": true and fill in domain (a description and keywords that define what counts as on-topic). Tune denylist_dirs/allowlist_dirs, min_transcript_bytes, and the capture/lint blocks as needed. (MINDGAP_CAPTURE_ENABLED env-overrides the flag.)
Register the hook globally in ~/.claude/settings.json under SessionEnd, pointing at mindgap-capture-hook (on PATH after install, or ./bin/mindgap-capture-hook from a source checkout).
The pre-gate skips off-domain dirs, denylisted dirs, capture's own self-spawned sessions (MINDGAP_CAPTURE=1), too-small transcripts, and transcripts with no domain keywords — so the LLM subagent only ever runs on genuinely on-topic sessions. A best-effort lock (~/.mindgap/capture.lock) single-flights it. The hook never blocks session exit.
mindgap lint is the companion: a deterministic health report (orphans, dangling stubs, near-duplicate candidates, stale capture nodes) that never rewrites the graph.
The bundle ships self-improving loop templates that sweep arXiv for a topic and ingest
findings into your graph with evidence-backed links — driven by the loop-system skill.
List what's available and scaffold one: mindgap loop list mindgap loop new arxiv-weekly --name my-watch --topics "your research area"
Then just tell Claude (in the project where you scaffolded it): "continue the my-watch loop"
Bundled templates:
arxiv-weekly — recurring weekly 7-day arXiv sweep; tags every find, self-tunes its query
strategy each pass. Schedule it unattended via the generated CRON.md (launchd/cron).
paper-discovery — one-shot batch discovery of papers for a topic.
paper-links — densify the graph by finding missing links between existing papers.
implementation-ideation — mine the graph's growing connections for buildable ideas, then adversarially refute the infeasible ones; only vetted ideas (each with an MVP sketch) are ingested.
author-graph — build a person-node graph of the researchers behind the work, with their resolved GitHub / homepage / Scholar links and co-author connections.
Share a loop you've built (strips your accumulated state): mindgap loop export my-watch # -> ./my-watch-template/ mindgap loop import ./my-watch-template --name their-watch --topics "..."
Prompts you can hand to Claude directly (once the plugin is installed):
"set up an arxiv-weekly loop watching and run the first pass"
"continue the loop"
"export the loop as a template I can share"
"ideate implementations from the growing connections in my graph, and refute the ones that aren't feasible" (implementation-ideation)
"build a graph of the authors doing work, with their github pages" (author-graph)
The bundled arxiv-explainer skill turns a paper into a richly animated, narrated HTML explainer — figures extracted from the PDF, a self-contained dark theme — and ingests it into your graph. Just tell Claude explain <arXiv link> (or point it at a local PDF).
Mine your Papers (ReadCube) reference library into the graph: export it to BibTeX or RIS (Papers → Settings → Export) and tell Claude:
"import my Papers library from <path-to-export.bib>"The bundled papers-library skill parses the export (stdlib, no deps), ingests each paper as a node (deduped against the graph, evidence-linked), discovers related papers not yet in your library, and seeds ideas — handing off to the paper-links / implementation-ideation loops for depth.
Two tables:
nodes(id, title, type, body, tags, urls, confidence, created_by, created_at, updated_at) — id is a kebab-case slug; tags/urls are JSON arrays; types: concept|definition|software|repo|page|paper|person|team|stub.
edges(src, dst, rel, weight, created_by, created_at) — rels: relates_to|defines|implements|depends_on|cites|part_of|mentions.
[[wiki-links]] in a body sync to mentions edges automatically, creating stub nodes for missing targets. Upserts merge: scalar fields replace, tags/urls union.
The DB is gitignored; history is kept as JSON snapshots:
mindgap export # ~/.mindgap/snapshots/<utc>.json
mindgap export --out my.jsonCommit snapshots for a durable, diffable record; re-ingest one with mindgap ingest FILE to restore.
python3 -m mindgap ... # run CLI from repo without install
python3 -m unittest discover testsMIT — see LICENSE.
Single node upsert. Returns the persisted row plus stubs_created and warnings. confidence defaults to 0.7.
| Name | Required | Description | Default |
|---|---|---|---|
| created_by | Yes | ||
| title | Yes | ||
| id | No | ||
| type | No | ||
| body | No | ||
| tags | No | ||
| urls | No | ||
| confidence | No | ||
| replace | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions 'upsert' (implies insert or update), return values (persisted row, stubs_created, warnings), and a default for confidence. Missing details on idempotency, conflict behavior, permissions, or destructive potential.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. Front-loaded with the core action. However, could be slightly more structured to include parameter hints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, no schema descriptions, and no output schema, the description is incomplete. Lacks explanation of upsert semantics, meaning of 'stubs_created', and details on 'replace' behavior. Significant gaps for proper tool usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. Only the 'confidence' parameter is explained as defaulting to 0.7. Other key parameters like 'replace', 'id', 'type', 'tags', 'urls' are not described, leaving the agent uninformed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Single node upsert', which is a specific verb+resource combination. It distinguishes from sibling tools like mindgap_get_node (read) and mindgap_remove_node (delete). However, 'upsert' is jargon and might not be universally understood.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as mindgap_ingest or mindgap_get_node. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a markdown digest (matched nodes + neighbor links) for a query, mirroring mindgap context. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| depth | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description declares 'Read-only', which is a key behavioral trait. However, with no annotations provided, it should disclose more (e.g., whether it modifies state, what side effects exist). It adds the fact that it mirrors 'mindgap context', but lacks details on output format or performance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 15 words, highly concise and front-loaded with the action 'Render a markdown digest'. No unnecessary information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two parameters and no output schema, the description omits explanation of the 'depth' parameter, does not specify the return format beyond 'markdown', and lacks differentiation from similar query tools (e.g., mindgap_find). More context on neighbor links and expected output is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters (query, depth) with 0% description coverage. The description only mentions 'for a query', partially explaining the 'query' parameter, but omits depth entirely. It fails to add meaning beyond the schema field names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'renders a markdown digest (matched nodes + neighbor links) for a query', which is a specific verb+resource. It distinguishes from siblings like 'add_node' or 'export' by focusing on query-based digest, though it could be more explicit about difference from 'mindgap_find'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Read-only' implying safe usage, but provides no guidance on when to use this tool versus alternatives like 'mindgap_find' or 'mindgap_get_node'. No exclusions or alternative suggestions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a JSON snapshot of the whole graph. Default path data/snapshots/.json; absolute out path allowed.
| Name | Required | Description | Default |
|---|---|---|---|
| out | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It mentions the default output path and that absolute paths are allowed, but does not specify whether the operation is destructive, requires permissions, or if it captures all data types. The behavior beyond file naming is opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. The first sentence states the core function, and the second adds key parameter detail. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema, no annotations), the description covers the essential: what it does and the parameter behavior. It does not explain return values or confirm comprehensiveness of the snapshot, but for an export tool, it is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one optional parameter 'out' with no description. The tool description adds meaning by stating the default path pattern and that an absolute path is allowed. With 0% schema coverage, the description compensates well, though it could be more precise about the parameter format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Write a JSON snapshot of the whole graph', which is a specific verb ('write') and resource ('JSON snapshot of the whole graph'). This clearly distinguishes it from sibling tools like 'mindgap_add_node' or 'mindgap_ingest'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks any guidance on when to use this tool versus alternatives. It does not suggest when not to use it or compare to other tools like 'mindgap_get_node' or 'mindgap_stats'. The usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search nodes by query/type/tag. Returns results + count (limit 1..200, default 50).
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| type | No | ||
| tag | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It mentions returns results + count and limit range, but lacks details on search behavior (e.g., exact vs fuzzy, case sensitivity, or what fields returned). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, very concise and front-loaded with purpose. Could add more detail without being verbose, but acceptable for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, no annotations, and only 0% parameter coverage. Description omits return format details (just 'results'), and doesn't clarify search behavior. Incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description should explain each parameter. It mentions 'query/type/tag' and limit with bounds, but does not define what query, type, or tag mean. The limit is well-documented, but the others are unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches nodes by query, type, and tag, and returns results with a count. This distinguishes it from sibling tools that add, get, remove, or link nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies use for searching/finding nodes, but does not explicitly state when to use this versus alternatives like mindgap_get_node or mindgap_stats. No when-not or alternative tool guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a node and its neighborhood (depth 1..3, default 1). Missing id returns node:null (clean miss, not an error).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| depth | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that a missing id returns node:null (clean miss, not an error) and notes the default depth. This is transparent for a simple read operation, though it omits discussion of authentication or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. All information is front-loaded and essential.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with 2 params and no output schema, the description covers purpose, depth behavior, and missing-id behavior. However, it does not describe the return structure (e.g., node data and neighborhood format), which would be helpful. Still, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds meaning for 'depth' (range 1..3, default 1) but does not clarify what 'id' represents (e.g., node ID string). The missing-id behavior is about the result, not the parameter meaning. Partial coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'a node and its neighborhood'. It specifies the depth range (1..3) with a default of 1, and distinguishes this read operation from siblings like mindgap_add_node or mindgap_remove_node.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for fetching a node and its neighbors, but it does not explicitly state when to use this tool versus alternatives like mindgap_find or mindgap_context. No when-not or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validated batch write (workhorse). Upserts nodes + adds edges in one transaction; rejects the WHOLE payload (no partial commit) if any edge endpoint is neither in the DB nor in the payload. Returns the persisted rows so a caller can't claim a write that didn't land.
| Name | Required | Description | Default |
|---|---|---|---|
| created_by | Yes | ||
| nodes | No | ||
| edges | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: atomic validation (rejecting entire payload if any edge endpoint is invalid) and return of persisted rows for verification. No annotations provided, so description fully carries the burden, and it does so well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that are concise and front-loaded with the most important identity ('Validated batch write (workhorse)'). Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description explains the return value (persisted rows) and validation behavior. It covers key aspects for a batch write tool, though more details on parameter constraints would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% parameter description coverage. Description only mentions 'nodes' and 'edges' generically, with no details on fields like created_by, id, etc. No compensation for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it performs a validated batch write that upserts nodes and adds edges in one transaction. Distinguished from siblings like mindgap_add_node (single node) and mindgap_link (single edge) by being a batch 'workhorse'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly indicates it's the primary tool for batch operations ('workhorse'), but does not explicitly state when to use alternatives or exclude cases. Clear context but lacks direct when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one edge between two EXISTING nodes. Hard-fails (isError) if either endpoint is missing — does not auto-stub.
| Name | Required | Description | Default |
|---|---|---|---|
| created_by | Yes | ||
| src | Yes | ||
| dst | Yes | ||
| rel | No | ||
| weight | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses the hard-fail (isError) behavior on missing endpoints and confirms no auto-stubbing. This is good transparency for the core mutation, though no side effects or permissions mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, economical and front-loaded. Every word earns its place – no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters and no output schema, the description is incomplete. It explains the error condition but ignores parameter semantics, return value, and potential side effects. The agent cannot reliably invoke the tool without guessing parameter meanings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no parameter documentation. The 5 parameters (created_by, src, dst, rel, weight) are entirely unexplained, leaving the agent without guidance on their meaning or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds an edge between two existing nodes, with a specific verb 'Add' and resource 'edge'. It explicitly says 'EXISTING' to differentiate from node creation, and contrasts with sibling tools like mindgap_add_node and mindgap_unlink.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use: when linking existing nodes, and not when endpoints might be missing (since it hard-fails). It does not explicitly list alternatives or when-not-to-use, but the hard-fail behavior is a strong guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a node (cascades its edges). Destructive; for stub cleanup.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden; it discloses cascading of edges and destructiveness, enough for a simple delete tool, but omits auth needs or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with essential info, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a low-complexity tool with one param and no output schema; covers core action and side effect, though return value or error details are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage for the single 'id' parameter; description adds no meaning beyond the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete a node (cascades its edges)' with specific verb and resource, and distinguishes from siblings that add or link nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use for stub cleanup and labels it destructive, but lacks explicit when-to-use vs alternatives like mindgap_unlink for edge removal or mindgap_get_node for inspection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Graph counts: {nodes, edges, by_type, by_rel}.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only lists output fields but does not state whether the tool is read-only, requires authentication, or has side effects. Key behavioral information is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that immediately conveys the tool's purpose. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with no output schema, the description provides the core output fields but lacks details on scope (e.g., which graph), limitations, or response format. It is minimally adequate but could be more descriptive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema has 100% description coverage (empty). Per guidelines, baseline is 4. The description adds no parameter info, which is acceptable since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly indicates the tool returns graph counts including nodes, edges, and breakdowns by type and relationship. While the verb is implied, the resource ('graph') and output types are explicit, distinguishing it from sibling tools that modify or search the graph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like mindgap_find or mindgap_context. The description lacks context about prerequisites, typical use cases, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete edge(s) between src and dst (optionally a specific rel). Returns removed count and any nodes left edgeless.
| Name | Required | Description | Default |
|---|---|---|---|
| src | Yes | ||
| dst | Yes | ||
| rel | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the destructive action (delete), the return value (removed count and orphaned nodes), and side effects. However, with no annotations, it could further clarify permanence or permissions needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words; all essential information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-param tool with no output schema, the description covers the action, parameters, and return info well. Could be improved by mentioning when to use this vs. siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains that src and dst are endpoints and rel is optional, adding some meaning beyond the schema param names. But it does not provide data types, format, or examples, and schema coverage is 0%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Delete) and resource (edge(s)) between src and dst, and distinguishes from siblings like mindgap_link (which adds edges) and mindgap_remove_node (which removes nodes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like mindgap_link or mindgap_remove_node. No context on prerequisites or typical usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0mindgap_add_nodemindgap_contextmindgap_exportmindgap_findmindgap_get_nodemindgap_ingestmindgap_linkmindgap_remove_nodemindgap_statsmindgap_unlinkEach tool has a clear, distinct purpose with no overlap. For example, add_node handles single upsert, ingest handles batch writes, link and unlink are opposites, find and get_node serve different retrieval needs, and context provides a digest rendering.
All tools share the 'mindgap_' prefix and use clear verbs, but some are verb_noun (add_node, get_node, remove_node) while others are single verbs (context, export, find, ingest, link, stats, unlink), representing a minor inconsistency.
With 10 tools, the set is well-scoped for a graph knowledge base server, covering core operations without being overly large or insufficient. Each tool serves a necessary function.
The tools cover CRUD-like operations via upsert, batch ingest, retrieval, search, linking, unlinking, stats, export, and context rendering. Minor gaps include lack of explicit update tool (handled by upsert) and dedicated tag management, but core workflows are well-supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/grburgess/mindgap'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
