# Cued MCP Server

[![npm version](https://badge.fury.io/js/%40cued%2Fmcp.svg)](https://www.npmjs.com/package/@cued/mcp)
[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js CI](https://github.com/Cue-d/mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Cue-d/mcp/actions)

**MCP server for Cued** — Enable Claude to access your local messages and contacts via Model Context Protocol.

Cued is a [local-first](https://www.inkandswitch.com/local-first/) message and contact datastore for AI agents. This MCP server bridges Cued and Claude, letting you:

- 🔍 **Search messages** across all platforms (iMessage, Discord, Gmail, Slack, etc.)
- 📋 **Query contacts** from your synchronized address book
- 🔄 **Trigger platform syncs** on-demand
- 📊 **Get message statistics** by platform
- 💾 **Export conversations** to JSON or CSV
- 🏥 **Run diagnostics** to verify installation and permissions

Everything stays **local and private** — data never leaves your Mac.

## Installation

### Via npm (Recommended)

```bash
npm install -g @cued/mcp
```

### From Source

```bash
git clone https://github.com/Cue-d/mcp.git
cd mcp
npm install
npm run build
```

## Quick Start

### 1. Start the MCP Server

```bash
# Via CLI
cued-mcp start

# Or via Node.js
node /path/to/cued-mcp/dist/index.js
```

### 2. Configure Claude Code

Add to `.claude/mcp.json`:

```json
{
  "mcpServers": {
    "cued": {
      "command": "node",
      "args": ["/path/to/cued-mcp/dist/cli.js"]
    }
  }
}
```

Replace `/path/to/cued-mcp` with your actual installation path. Find it with:
```bash
npm list -g @cued/mcp
```

### 3. Use in Claude

```
You: "Search my messages for 'project update' from the last week"
Claude: [Uses cued_search_messages tool]
→ Returns matching messages with context
```

## CLI Usage

### Start MCP Server

```bash
cued-mcp start
# or
cued-mcp server
```

### Daemon Mode

#### Start Background Daemon

```bash
# Both PID-based and macOS launchd
cued-mcp daemon start both

# PID-based only (cross-platform)
cued-mcp daemon start pid

# macOS launchd only (native integration, auto-start)
cued-mcp daemon start launchd
```

#### Check Status

```bash
cued-mcp daemon status
# Output:
# [cued-mcp] PID daemon: running (PID: 12345)
# [cued-mcp] Launchd daemon: running
```

#### Stop Daemon

```bash
cued-mcp daemon stop both
```

#### View Logs

```bash
# Last 50 lines
cued-mcp daemon logs

# Last 100 lines
cued-mcp daemon logs 100
```

## Available Tools

### `cued_status`
Get current system status and health.

```
Claude: "Check my Cued status"
→ {healthy: true, database_path: "~/.cued/local.db", ...}
```

### `cued_integrations_status`
View connected integrations and their sync status.

```
Claude: "What integrations do I have connected?"
→ {integrations: [{platform: "imessage", status: "idle", ...}, ...]}
```

### `cued_sync_run`
Trigger a sync for a specific platform.

```
Claude: "Sync my Gmail"
→ Starts sync, returns status
```

**Supported platforms:** `imessage`, `contacts`, `discord`, `gmail`, `slack`, `signal`, `whatsapp`, `linkedin`

### `cued_search_messages`
Search messages by text, platform, or date range.

```
Claude: "Find messages about 'quarterly review' from June"
→ [{id: "msg_123", from: "alice@...", body: "quarterly review...", ...}]
```

**Parameters:**
- `query` (required) — Search term
- `platform` — Filter by platform (e.g., "discord", "imessage")
- `from` — Unix timestamp (earliest date)
- `to` — Unix timestamp (latest date)
- `limit` — Max results (default: 10, max: 100)
- `offset` — Pagination offset

### `cued_get_contacts`
Get contacts with pagination.

```
Claude: "Show me my top 20 contacts"
→ [{id: "...", name: "Alice", email: "alice@...", ...}]
```

**Parameters:**
- `limit` — Max results (default: 20, max: 100)
- `offset` — Pagination offset (default: 0)

### `cued_get_contacts_by_platform`
Filter contacts by platform.

```
Claude: "Who are my Discord contacts?"
→ [{id: "...", name: "Bob", platform: "discord", ...}]
```

### `cued_message_stats`
Get message count by platform.

```
Claude: "How many messages do I have per platform?"
→ {total: 12345, by_platform: {imessage: 5000, discord: 4000, ...}}
```

### `cued_get_thread`
Get all messages in a conversation thread.

```
Claude: "Show me the full conversation thread with Alice"
→ [{id: "msg_1", from: "alice", ...}, {id: "msg_2", from: "me", ...}, ...]
```

### `cued_export_messages`
Export messages to JSON or CSV format.

```
Claude: "Export my Discord messages as CSV"
→ Returns CSV file content as string
```

**Formats:** `json`, `csv`

### `cued_doctor`
Run diagnostics and check system health.

```
Claude: "Run Cued diagnostics"
→ Detailed diagnostic report
```

## Configuration

### Environment Variables

```bash
# Optional: Require token for API access
export CUED_MCP_TOKEN="your-secret-token"

# Set to production for deployments
export NODE_ENV="production"
```

### Programmatic Usage

```typescript
import { startServer } from "@cued/mcp";

// Start the MCP server
await startServer();
```

### Daemon Configuration

The daemon stores state in `~/.cued/`:
- `~/.cued/mcp.pid` — PID-based daemon process ID
- `~/.cued/mcp.log` — Combined stdout/stderr logs
- `~/Library/LaunchAgents/com.cued.mcp.plist` — macOS launchd configuration (macOS only)

## Security & Privacy

✅ **Local-first** — All data stays in `~/.cued/local.db`  
✅ **No cloud sync** — Your messages never leave your Mac  
✅ **No external APIs** — MCP server doesn't call third-party services  
✅ **User auth** — Uses Cued's existing authentication and permissions  
✅ **Optional token auth** — Add `CUED_MCP_TOKEN` for extra security  

## Requirements

- **Node.js** 18+
- **Cued** installed and configured
  - Check: `cued doctor`
- **macOS** (Cued is macOS-only for now)

## Troubleshooting

### "Command 'cued' not found"

Ensure Cued is installed:
```bash
cued doctor
which cued
```

If not installed, install Cued:
```bash
# Visit https://github.com/Cue-d/cued for installation instructions
```

### Database query failed

Check database exists:
```bash
ls -la ~/.cued/local.db
```

Run Cued setup:
```bash
cued setup
```

### MCP Server won't start

Check Node.js version:
```bash
node --version  # Need 18+
```

Check logs:
```bash
cued-mcp daemon logs 50
```

### Permission denied errors

Ensure file permissions:
```bash
chmod 600 ~/.cued/local.db
```

### Daemon won't stop

Kill manually:
```bash
# Find process
ps aux | grep cued-mcp

# Kill by PID
kill -9 <PID>

# Remove stale PID file
rm ~/.cued/mcp.pid
```

## Development

### Setup

```bash
git clone https://github.com/Cue-d/mcp.git
cd mcp
npm install
```

### Build

```bash
npm run build          # Compile TypeScript
npm run dev            # Watch mode
npm run lint           # Run ESLint
npm run lint:fix       # Auto-fix linting issues
```

### Test

```bash
npm test               # Run all tests
npm run test:watch    # Watch mode
```

### Local Development

```bash
# Start in watch mode
npm run dev

# In another terminal, test with Claude
claude mcp test cued
```

## Contributing

Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Areas for Contribution

- 🧪 Additional test coverage
- 📚 Documentation improvements
- ✨ New tools (e.g., message summarization, smart search)
- 🐛 Bug fixes
- ⚡ Performance improvements

## Architecture

For technical details, see [ARCHITECTURE.md](ARCHITECTURE.md).

### High-Level Data Flow

```
Claude AI
    ↓
MCP Server (Node.js)
    ↓
├─→ Cued CLI (status, sync)
└─→ SQLite DB (~/.cued/local.db)
    ↓
Local Message/Contact Store (Private)
```

## License

MIT — See [LICENSE](LICENSE) for details.

## Support

- **Issues**: [GitHub Issues](https://github.com/Cue-d/mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/Cue-d/mcp/discussions)
- **Cued Project**: [https://github.com/Cue-d/cued](https://github.com/Cue-d/cued)

## Related

- [Cued](https://github.com/Cue-d/cued) — Local-first message/contact datastore
- [Model Context Protocol](https://modelcontextprotocol.io/) — MCP spec
- [Claude API](https://docs.anthropic.com/) — Claude documentation
- [Anthropic](https://www.anthropic.com/) — Creator of Claude

---

**Made with ❤️ for AI agents that respect your privacy.**