Loading ToolBench
MCP server for personal knowledge brain — a vault of markdown notes with wikilink support, full-text search, and project context traversal
brain-mcp has 8 well-named tools with detailed descriptions (avg 180 chars, within baseline 194). All tools have input schemas with type definitions and parameter descriptions. However, output schemas are not documented, responses are returned as plain strings rather than structured objects. Error handling is minimal; tools return strings without guidance on recovery. No tool annotations (readOnlyHint/destructiveHint) despite clear risk profiles. Naming is strong (verb_noun pattern: brain_recent, brain_search, brain_write). Parameter descriptions are explicit and actionable. Missing: output schema documentation, error classification, and structured responses.
Call this BEFORE asking the user to re-explain a project. Traverses the project's full note graph starting from projects/<name>/index.md (depth 2) and returns all recorded context, decisions, and status in one call. Requires projects/<name>/index.md to exist — this is why every project needs one. Always try this first — the user may have already told you everything.
Add a wikilink from one existing note to another. Use after brain_write when two notes should reference each other but the link wasn't included in the initial content. Appends to an existing '## Related' section or creates one.
Read a specific note and resolve its wikilinks one level deep. Use when you need full content of a note plus its immediate neighbors. Accepts relative paths (e.g. 'projects/brain-mcp/index') or bare note stems.
Call this at the START of every session. Returns recently modified notes so you know what's in flight before diving in. Skipping this means working blind to decisions made in prior sessions.
Find all notes that contain a wikilink pointing TO a given note (backlinks). Use to discover what references a concept or decision without following forward links yourself.
No output schemas documented. All tools return plain strings; LLMs cannot parse structured results or chain downstream calls. brain_search_tool, brain_context_tool, and brain_read_tool should return JSON objects with fields like 'notes', 'links', 'metadata' so agents can extract and reuse data.
No tool annotations (readOnlyHint/destructiveHint). brain_write_tool and brain_link_tool are destructive (WRITE risk) but lack destructiveHint annotation. brain_recent_tool, brain_read_tool, brain_search_tool, brain_related_tool, brain_suggest_links_tool are read-only but lack readOnlyHint. Agents cannot distinguish safe from risky tools without explicit hints.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 58 | 2026-07-28+ | v2 |
Full-text search across all notes using ripgrep. Use when you don't know the exact path but know what you're looking for. Optionally filter by type (project/concept/person/decision/scratch) or project name.
Scan a block of text and suggest existing brain notes that should be wikilinked. Run this on new content before writing to catch missed connections.
Create or update a note in the brain vault. Call this at the END of any session where something non-obvious was learned, a decision was made, or output worth keeping was produced. PATH RULES (strictly enforced — the tool will error if violated): - Path is RELATIVE to vault root — never use absolute paths - Must start with one of: projects/, concepts/, people/, scratch/ - Project notes MUST be nested: projects/<project-name>/<file>.md e.g. projects/my-app/index.md, projects/my-app/decisions.md - projects/<name>/index.md MUST be created before any other file in that project folder - Quick capture: scratch/<topic>.md METADATA RULES (required on new notes — tool will error if missing): - Pass as a JSON string - Required fields: "type" and "tags" - "type" must be one of: project, concept, person, decision, scratch - "project" field required when type is project or decision - Example: '{"type": "project", "project": "my-app", "tags": ["backend"]}' Returns suggested wikilinks to add based on existing notes.
Error handling returns plain strings with no recovery guidance. brain_write_tool enforces strict PATH and METADATA rules but errors are not classified as retryable/user-fixable/fatal. Example: 'Invalid path' tells agent nothing; should be 'Invalid path: must start with projects/, concepts/, people/, or scratch/. Did you mean: projects/my-app/index.md?'
brain_write_tool metadata parameter is a JSON string, not a structured object. Agents must manually serialize JSON, risking malformed input. Should accept metadata as a structured object with type, tags, project fields.
No pagination support. brain_search_tool and brain_recent_tool return unbounded results. If vault contains 1000 notes, brain_search_tool could return all of them, exhausting context. Should accept limit and offset parameters and return total_count.