ideahub_mcp

An agent-first MCP server for capturing and recalling ideas — the agent's and their human's.

The primary user is a model. Tools are short, imperative, example-laden; errors carry a repair path; scope and actor resolve from context so the agent doesn't have to ask.

Tools

Writeback Loop

ideahub_mcp is designed to behave like working memory for an agent, not just searchable storage. Two write verbs close that loop:

• capture writes a durable idea that should survive the task.

• checkpoint writes a lightweight in-flight trace — observations, decisions, assumptions, open questions — without the semantic weight of a full idea.

When a checkpoint hardens into something load-bearing, promote flips its kind to idea while preserving the id, so existing links, annotations, and task_ref groupings carry forward unchanged. Promotion is one-way; an idea cannot be demoted.

All write-path verbs (capture, checkpoint, annotate, link) accept an optional task_ref — a free-form string that groups every write from the same task. It is normalized to lowercase kebab-case at the boundary, so "Writeback Phase 1", "writeback_phase_1", and "writeback-phase-1" collapse onto the same key.

capture and checkpoint return scored annotate_candidates and related_candidates in their response so the model sees where a fresh trace probably belongs (usually as an annotation on an existing idea) without having to search. The candidates parameter (default 5, max 10, 0 to skip) lets a caller cap or skip that envelope when fire-and-forget is the right move.

Checkpoints are default-excluded from search, list, and dump so cheap traces do not bleed into orientation surfaces — opt in with include_checkpoints=True.

Deduplication

capture runs two dedup paths before inserting:

• Fast path — same actor, same content, same scope, within 5 seconds: silently returns the existing id. This catches accidental double-fires.

• Content-hash path — same scope, same SHA-256 over normalized content (whitespace-collapsed, lowercased), any actor, any time, against live (non-archived) kind='idea' rows: returns the existing id, merges incoming tags into the row, and appends a kind='dup_attempt' note recording the second actor and tag delta.

Hash dedup makes re-derivation of the same idea observable in the row's note stream rather than silently creating duplicates.

Search

search defaults to query_mode='auto', which tokenizes the query and quotes each token so FTS5 operators (-, :, *, etc.) are treated as content. This is the right mode for searching kebab-case identifiers — task_refs, branch names, ULIDs.

For phrase queries, NEAR, or column-qualified syntax, pass query_mode='raw'. Raw mode validates the query and raises a loud error on syntax failure rather than the silent empty-result FTS5 returns by default.

Discovery And Health

ideahub_mcp is intentionally tool-first, not resource-first. A client may show a healthy connection even when list_resources() is sparse or empty.

To make discovery cheap and host-agnostic, the server exposes:

• ping: a no-side-effect tool for "is the server connected and responsive?"

• ideahub://status: a status resource that reports package version, storage paths, and the current tool surface.

That design supports hosts that favor different MCP surfaces. Some clients reason primarily over tools. Others probe resources first. A healthy server should be easy to verify in either style.

For the full compatibility rubric, see docs/mcp-health.md.

Install

uvx ideahub_mcp        # try it
uv tool install ideahub_mcp   # keep it around

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "ideahub": {
      "command": "uvx",
      "args": ["ideahub_mcp"],
      "env": {
        "IDEAHUB_MCP_HOME": "/Users/you/.ideahub_mcp",
        "IDEAHUB_ACTOR": "human:you"
      }
    }
  }
}

Configuration

Actor resolution: explicit arg → MCP clientInfo.name → IDEAHUB_ACTOR → error. Scope resolution: explicit arg → IDEAHUB_SCOPE → repo:<git-toplevel> → global.

Storage

One SQLite file with WAL, FTS5, and hand-rolled migrations. No ORM. Daily snapshots to $IDEAHUB_MCP_HOME/backups/ with 14-day retention.

Develop

uv sync --dev
uv run pytest
uv run ruff check .
uv run pyright

License

MIT.