Metadata-Version: 2.4
Name: ideahub-mcp
Version: 0.1.2
Summary: Agent-first MCP server for capturing and recalling ideas — the agent's and their human's.
Project-URL: Homepage, https://github.com/CobraChickenAI/ideahub-mcp
Project-URL: Repository, https://github.com/CobraChickenAI/ideahub-mcp
Project-URL: Issues, https://github.com/CobraChickenAI/ideahub-mcp/issues
Author-email: Michael Schartung <michael@cobrachicken.ai>
License: MIT
License-File: LICENSE
Keywords: agent,agent-memory,capture,fastmcp,ideas,mcp,mcp-server,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.13
Requires-Dist: fastmcp>=2.0
Requires-Dist: pydantic>=2.7
Requires-Dist: python-ulid>=3.0
Requires-Dist: structlog>=24.0
Description-Content-Type: text/markdown

# <span data-proof="authored" data-by="ai:claude">ideahub-mcp</span>

An agent-first [MCP](https://modelcontextprotocol.io) 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

| Tool        | Purpose                                                                   |
| ----------- | ------------------------------------------------------------------------- |
| `capture`   | Write a new idea. Idempotent within 5s on identical content.              |
| `dump`      | Text-blob summary of the scoped corpus under a token budget.              |
| `search`    | FTS5 + bm25 ranked search with snippets.                                  |
| `list`      | Filter ideas by scope, actor, tags, date range.                           |
| `get`       | Full detail for one idea, with notes and outbound links.                  |
| `related`   | Nearest neighbors by tag overlap → shared originator → recency.           |
| `annotate`  | Append a free-text note to an idea without mutating it.                   |
| `archive`   | Hide an idea; write a typed `archive` note with reason.                   |
| `link`      | Connect two ideas (`related`, `supersedes`, `evolved_from`, `duplicate`). |
| `recognize` | Inspect the actor table.                                                  |

## Install

```bash
uvx ideahub-mcp        # try it
uv tool install ideahub-mcp   # keep it around
```

## Claude Code

Add to `~/.claude/settings.json`:

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

## Configuration

| Var                                                                       | Default                                                                  | Purpose                                          |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------ |
| <span data-proof="authored" data-by="ai:claude">`IDEAHUB_MCP_HOME`</span> | <span data-proof="authored" data-by="ai:claude">`~/.ideahub-mcp/`</span> | Data directory (SQLite store, logs, backups).    |
| <span data-proof="authored" data-by="ai:claude">`IDEAHUB_ACTOR`</span>    | —                                                                        | Fallback actor id (`human:you` or `agent:name`). |
| <span data-proof="authored" data-by="ai:claude">`IDEAHUB_SCOPE`</span>    | —                                                                        | Fallback scope when cwd isn't a git repo.        |

Actor resolution: explicit arg → MCP `clientInfo.name` → `IDEAHUB_ACTOR` → error.
Scope resolution: explicit arg → `IDEAHUB_SCOPE` → `repo:<git-toplevel>` → <span data-proof="authored" data-by="ai:claude">`global`</span>.

## 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

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

## License

MIT.