# AIqel MCP Server

`@aiqel/mcp` is a [Model Context Protocol](https://modelcontextprotocol.io)
server (stdio transport) that exposes AIqel's public API as MCP tools. Any
MCP-capable client (Claude Desktop, Claude Code, custom agents) can then search
AIqel's knowledge and push new content — without knowing the REST details.

It is a thin wrapper: each tool calls the corresponding `/v1/*` endpoint
(documented in [API.md](./API.md)) with your API key.

---

## Configuration

The server reads two environment variables:

| Variable        | Required | Default                  | Purpose                          |
| --------------- | -------- | ------------------------ | -------------------------------- |
| `AIQEL_API_URL` | no       | `http://localhost:3001`  | Base URL of the AIqel API        |
| `AIQEL_API_KEY` | yes      | —                        | A minted AIqel API key (Bearer)  |

Mint a key via the admin endpoint or the `create-api-key.ts` script — see the
Authentication section of [API.md](./API.md).

---

## Running

```bash
AIQEL_API_URL=http://localhost:3001 \
AIQEL_API_KEY=aiqel_XXXX… \
pnpm --filter @aiqel/mcp start
# (equivalently: tsx src/index.ts)
```

The server speaks MCP over **stdio**, so it is normally launched by an MCP
client rather than run by hand.

### MCP client config snippet

```jsonc
{
  "mcpServers": {
    "aiqel": {
      "command": "tsx",
      "args": ["apps/mcp/src/index.ts"],
      "env": {
        "AIQEL_API_URL": "http://localhost:3001",
        "AIQEL_API_KEY": "aiqel_XXXX…"
      }
    }
  }
}
```

(Use an absolute path to `apps/mcp/src/index.ts`, or the `aiqel-mcp` bin, as
your client requires.)

---

## Tools

| Tool               | Wraps                    | Arguments                                        |
| ------------------ | ------------------------ | ------------------------------------------------ |
| `search_knowledge` | `POST /v1/search`        | `query`                                          |
| `add_item`         | `POST /v1/items`         | `type` (`audio`\|`text`), `title?`, `audioUrl?`, `text?` |
| `get_item`         | `GET /v1/items/:id`      | `id`                                             |
| `add_source`       | `POST /v1/sources`       | `type`, `url?`, `title`                          |
| `list_items`       | `GET /v1/items`          | `status?`, `limit?`                              |

Each tool returns the endpoint's JSON response as text content. Errors (network,
auth, non-2xx) come back as an MCP error result with the message.

### Typical agent flow

1. `add_item` to submit audio/text → note the returned `id`.
2. `list_items` (or `get_item`) to poll until processing completes.
3. `get_item` to read the transcript, translations and insight blocks.
4. `search_knowledge` any time to retrieve relevant insights across everything
   AIqel has processed.