# idea-basin-mcp

MCP server for [Idea Basin](https://github.com/MsFixer101/idea-basin) — a semantic knowledge graph with vector search, hierarchical organization, and automatic content ingestion.

Gives Claude (and any MCP-compatible AI assistant) the ability to search, browse, and save to your personal knowledge base.

## How it works

```mermaid
flowchart LR
    subgraph client["AI Assistant"]
        Claude["Claude / Any MCP Client"]
    end

    subgraph mcp["idea-basin-mcp"]
        direction TB
        T1["search_knowledge"]
        T2["browse_nodes"]
        T3["get_node"]
        T4["save_resource"]
        T5["fetch_and_save"]
    end

    subgraph basin["Idea Basin Server :3500"]
        API["REST API"]
        Embed["Embedder"]
        Scraper["Scraper"]
    end

    subgraph storage["Storage"]
        PG[("PostgreSQL + pgvector")]
    end

    Claude -- "stdio / JSON-RPC" --> mcp
    mcp -- "HTTP" --> API
    API --> Embed
    API --> Scraper
    API --> PG
```

## Tools

| Tool | Description |
|------|-------------|
| `search_knowledge` | Semantic similarity search across all knowledge chunks |
| `browse_nodes` | Browse the knowledge graph tree structure (3 levels deep) |
| `get_node` | Inspect a node with its children and resources |
| `save_resource` | Save a note, research, link, code, or idea to a node |
| `fetch_and_save` | Fetch a URL (web page, YouTube, GitHub, arXiv, PDF) and save it |

## Prerequisites

A running [Idea Basin](https://github.com/MsFixer101/idea-basin) server (default: `http://localhost:3500`).

## Install

### Claude Code

```bash
claude mcp add idea-basin -- node /path/to/idea-basin-mcp/build/index.js
```

Or with a custom Basin URL:

```bash
claude mcp add idea-basin -e IDEA_BASIN_URL=http://localhost:3500 -- node /path/to/idea-basin-mcp/build/index.js
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "idea-basin": {
      "command": "node",
      "args": ["/path/to/idea-basin-mcp/build/index.js"],
      "env": {
        "IDEA_BASIN_URL": "http://localhost:3500"
      }
    }
  }
}
```

### npm (once published)

```bash
npx idea-basin-mcp
```

## Configuration

| Env var | Default | Description |
|---------|---------|-------------|
| `IDEA_BASIN_URL` | `http://localhost:3500` | Base URL of your Idea Basin server |

## Development

```bash
npm install
npm run build    # TypeScript → build/
npm run dev      # Watch mode
```

## License

MIT