basicmachines-co-basic-memory/v15-docs/chatgpt-integration.md

# ChatGPT MCP Integration

**Status**: New Feature
**PR**: #305
**File**: `mcp/tools/chatgpt_tools.py`
**Mode**: Remote MCP only

## What's New

v0.15.0 introduces ChatGPT-specific MCP tools that expose Basic Memory's search and fetch functionality using OpenAI's required tool schema and response format.

## Requirements

### ChatGPT Plus/Pro Subscription

**Required:** ChatGPT Plus or Pro subscription
- Free tier does NOT support MCP
- Pro tier includes MCP support

**Pricing:**
- ChatGPT Plus: $20/month
- ChatGPT Pro: $200/month (includes advanced features)

### Developer Mode

**Required:** ChatGPT Developer Mode
- Access to MCP server configuration
- Ability to add custom MCP servers

**Enable Developer Mode:**
1. Open ChatGPT settings
2. Navigate to "Advanced" or "Developer" settings
3. Enable "Developer Mode"
4. Restart ChatGPT

### Remote MCP Configuration

**Important:** ChatGPT only supports **remote MCP servers**
- Cannot use local MCP (like Claude Desktop)
- Requires publicly accessible MCP server
- Basic Memory must be deployed and reachable

## How It Works

### ChatGPT-Specific Format

OpenAI requires MCP responses in a specific format:

**Standard MCP (Claude, etc.):**
```json
{
  "results": [...],
  "total": 10
}
```

**ChatGPT MCP:**
```json
[
  {
    "type": "text",
    "text": "{\"results\": [...], \"total\": 10}"
  }
]
```

**Key difference:** ChatGPT expects content wrapped in `[{"type": "text", "text": "..."}]` array

### Adapter Architecture

```
ChatGPT Request
    ↓
ChatGPT MCP Tools (chatgpt_tools.py)
    ↓
Standard Basic Memory Tools (search_notes, read_note)
    ↓
Format for ChatGPT
    ↓
[{"type": "text", "text": "{...json...}"}]
    ↓
ChatGPT Response
```

## Available Tools

### 1. search

Search across the knowledge base.

**Tool Definition:**
```json
{
  "name": "search",
  "description": "Search for content across the knowledge base",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      }
    },
    "required": ["query"]
  }
}
```

**Example Request:**
```json
{
  "query": "authentication system"
}
```

**Example Response:**
```json
[
  {
    "type": "text",
    "text": "{\"results\": [{\"id\": \"auth-design\", \"title\": \"Authentication Design\", \"url\": \"auth-design\"}], \"total_count\": 1, \"query\": \"authentication system\"}"
  }
]
```

**Parsed JSON:**
```json
{
  "results": [
    {
      "id": "auth-design",
      "title": "Authentication Design",
      "url": "auth-design"
    }
  ],
  "total_count": 1,
  "query": "authentication system"
}
```

### 2. fetch

Fetch full contents of a document.

**Tool Definition:**
```json
{
  "name": "fetch",
  "description": "Fetch the full contents of a search result document",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Document identifier"
      }
    },
    "required": ["id"]
  }
}
```

**Example Request:**
```json
{
  "id": "auth-design"
}
```

**Example Response:**
```json
[
  {
    "type": "text",
    "text": "{\"id\": \"auth-design\", \"title\": \"Authentication Design\", \"text\": \"# Authentication Design\\n\\n...\", \"url\": \"auth-design\", \"metadata\": {\"format\": \"markdown\"}}"
  }
]
```

**Parsed JSON:**
```json
{
  "id": "auth-design",
  "title": "Authentication Design",
  "text": "# Authentication Design\n\n...",
  "url": "auth-design",
  "metadata": {
    "format": "markdown"
  }
}
```

## Configuration

### Remote MCP Server Setup

**Option 1: Deploy to Cloud**

```bash
# Deploy Basic Memory to cloud provider
# Ensure publicly accessible

# Example: Deploy to Fly.io
fly deploy

# Get URL
export MCP_SERVER_URL=https://your-app.fly.dev
```

**Option 2: Use ngrok for Testing**

```bash
# Start Basic Memory locally
bm mcp --port 8000

# Expose via ngrok
ngrok http 8000

# Get public URL
# → https://abc123.ngrok.io
```

### ChatGPT MCP Configuration

**In ChatGPT Developer Mode:**

```json
{
  "mcpServers": {
    "basic-memory": {
      "url": "https://your-server.com/mcp",
      "apiKey": "your-api-key-if-needed"
    }
  }
}
```

**Environment Variables (if using auth):**
```bash
export BASIC_MEMORY_API_KEY=your-secret-key
```

## Usage Examples

### Search Workflow

**User asks ChatGPT:**
> "Search my knowledge base for authentication notes"

**ChatGPT internally calls:**
```json
{
  "tool": "search",
  "arguments": {
    "query": "authentication notes"
  }
}
```

**Basic Memory responds:**
```json
[{
  "type": "text",
  "text": "{\"results\": [{\"id\": \"auth-design\", \"title\": \"Auth Design\", \"url\": \"auth-design\"}, {\"id\": \"oauth-setup\", \"title\": \"OAuth Setup\", \"url\": \"oauth-setup\"}], \"total_count\": 2, \"query\": \"authentication notes\"}"
}]
```

**ChatGPT displays:**
> I found 2 documents about authentication:
> 1. Auth Design
> 2. OAuth Setup

### Fetch Workflow

**User asks ChatGPT:**
> "Show me the Auth Design document"

**ChatGPT internally calls:**
```json
{
  "tool": "fetch",
  "arguments": {
    "id": "auth-design"
  }
}
```

**Basic Memory responds:**
```json
[{
  "type": "text",
  "text": "{\"id\": \"auth-design\", \"title\": \"Auth Design\", \"text\": \"# Auth Design\\n\\n## Overview\\n...full content...\", \"url\": \"auth-design\", \"metadata\": {\"format\": \"markdown\"}}"
}]
```

**ChatGPT displays:**
> Here's the Auth Design document:
>
> # Auth Design
>
> ## Overview
> ...

## Response Schema

### Search Response

```typescript
{
  results: Array<{
    id: string,        // Document permalink
    title: string,     // Document title
    url: string        // Document URL/permalink
  }>,
  total_count: number, // Total results found
  query: string        // Original query echoed back
}
```

### Fetch Response

```typescript
{
  id: string,          // Document identifier
  title: string,       // Document title
  text: string,        // Full markdown content
  url: string,         // Document URL/permalink
  metadata: {
    format: string     // "markdown"
  }
}
```

### Error Response

```typescript
{
  results: [],         // Empty for search
  error: string,       // Error type
  error_message: string // Error details
}
```

## Differences from Standard Tools

### ChatGPT Tools vs Standard MCP Tools

| Feature | ChatGPT Tools | Standard Tools |
|---------|---------------|----------------|
| **Tool Names** | `search`, `fetch` | `search_notes`, `read_note` |
| **Response Format** | `[{"type": "text", "text": "..."}]` | Direct JSON |
| **Parameters** | Minimal (query, id) | Rich (project, page, filters) |
| **Project Selection** | Automatic | Explicit or default_project_mode |
| **Pagination** | Fixed (10 results) | Configurable |
| **Error Handling** | JSON error objects | Direct error messages |

### Automatic Defaults

ChatGPT tools use sensible defaults:

```python
# search tool defaults
page = 1
page_size = 10
search_type = "text"
project = None  # Auto-resolved

# fetch tool defaults
page = 1
page_size = 10
project = None  # Auto-resolved
```

## Project Resolution

### Automatic Project Selection

ChatGPT tools use automatic project resolution:

1. **CLI constraint** (if `--project` flag used)
2. **default_project_mode** (if enabled in config)
3. **Error** if no project can be resolved

**Recommended Setup:**
```json
// ~/.basic-memory/config.json
{
  "default_project": "main",
  "default_project_mode": true
}
```

This ensures ChatGPT tools work without explicit project parameters.

## Error Handling

### Search Errors

```json
[{
  "type": "text",
  "text": "{\"results\": [], \"error\": \"Search failed\", \"error_details\": \"Project not found\"}"
}]
```

### Fetch Errors

```json
[{
  "type": "text",
  "text": "{\"id\": \"missing-doc\", \"title\": \"Fetch Error\", \"text\": \"Failed to fetch document: Not found\", \"url\": \"missing-doc\", \"metadata\": {\"error\": \"Fetch failed\"}}"
}]
```

### Common Errors

**No project found:**
```json
{
  "error": "Project required",
  "error_message": "No project specified and default_project_mode not enabled"
}
```

**Document not found:**
```json
{
  "id": "doc-123",
  "title": "Document Not Found",
  "text": "# Note Not Found\n\nThe requested document 'doc-123' could not be found",
  "metadata": {"error": "Document not found"}
}
```

## Deployment Patterns

### Production Deployment

**1. Deploy to Cloud:**
```bash
# Docker deployment
docker build -t basic-memory .
docker run -p 8000:8000 \
  -e BASIC_MEMORY_API_URL=https://api.basicmemory.cloud \
  basic-memory mcp --port 8000

# Or use managed hosting
fly deploy
```

**2. Configure ChatGPT:**
```json
{
  "mcpServers": {
    "basic-memory": {
      "url": "https://your-app.fly.dev/mcp"
    }
  }
}
```

**3. Enable default_project_mode:**
```json
{
  "default_project_mode": true,
  "default_project": "main"
}
```

### Development/Testing

**1. Use ngrok:**
```bash
# Terminal 1: Start MCP server
bm mcp --port 8000

# Terminal 2: Expose with ngrok
ngrok http 8000
# → https://abc123.ngrok.io
```

**2. Configure ChatGPT:**
```json
{
  "mcpServers": {
    "basic-memory-dev": {
      "url": "https://abc123.ngrok.io/mcp"
    }
  }
}
```

## Limitations

### ChatGPT-Specific Constraints

1. **Remote only** - Cannot use local MCP server
2. **No streaming** - Results returned all at once
3. **Fixed pagination** - 10 results per search
4. **Simplified parameters** - Cannot specify advanced filters
5. **No project selection** - Must use default_project_mode
6. **Subscription required** - ChatGPT Plus/Pro only

### Workarounds

**For more results:**
- Refine search query
- Use fetch to get full documents
- Deploy multiple searches

**For project selection:**
- Enable default_project_mode
- Or deploy separate instances per project

**For advanced features:**
- Use Claude Desktop with full MCP tools
- Or use Basic Memory CLI directly

## Troubleshooting

### ChatGPT Can't Connect

**Problem:** ChatGPT shows "MCP server unavailable"

**Solutions:**
1. Verify server is publicly accessible
   ```bash
   curl https://your-server.com/mcp/health
   ```

2. Check firewall/security groups
3. Verify HTTPS (not HTTP)
4. Check API key if using auth

### No Results Returned

**Problem:** Search returns empty results

**Solutions:**
1. Check default_project_mode enabled
   ```json
   {"default_project_mode": true}
   ```

2. Verify data is synced
   ```bash
   bm sync --project main
   ```

3. Test search locally
   ```bash
   bm tools search --query "test"
   ```

### Format Errors

**Problem:** ChatGPT shows parsing errors

**Check response format:**
```python
# Must be wrapped array
[{"type": "text", "text": "{...json...}"}]

# NOT direct JSON
{"results": [...]}
```

### Developer Mode Not Available

**Problem:** Can't find Developer Mode in ChatGPT

**Solution:**
- Ensure ChatGPT Plus/Pro subscription
- Check for feature rollout (may not be available in all regions)
- Contact OpenAI support

## Best Practices

### 1. Enable default_project_mode

```json
{
  "default_project_mode": true,
  "default_project": "main"
}
```

### 2. Use Cloud Deployment

Don't rely on ngrok for production:
```bash
# Production deployment
fly deploy
# or
railway up
# or
vercel deploy
```

### 3. Monitor Usage

```bash
# Enable logging
export BASIC_MEMORY_LOG_LEVEL=INFO

# Monitor requests
tail -f /var/log/basic-memory/mcp.log
```

### 4. Secure Your Server

```bash
# Use API key authentication
export BASIC_MEMORY_API_KEY=secret

# Restrict CORS
export BASIC_MEMORY_ALLOWED_ORIGINS=https://chatgpt.com
```

### 5. Test Locally First

```bash
# Test with curl
curl -X POST https://your-server.com/mcp/tools/search \
  -H "Content-Type: application/json" \
  -d '{"query": "test"}'
```

## Comparison with Claude Desktop

| Feature | ChatGPT | Claude Desktop |
|---------|---------|----------------|
| **MCP Mode** | Remote only | Local or Remote |
| **Tools** | 2 (search, fetch) | 17+ (full suite) |
| **Response Format** | OpenAI-specific | Standard MCP |
| **Project Support** | Default only | Full multi-project |
| **Subscription** | Plus/Pro required | Free (Claude) |
| **Configuration** | Developer mode | Config file |
| **Performance** | Network latency | Local (instant) |

**Recommendation:** Use Claude Desktop for full features, ChatGPT for convenience

## See Also

- ChatGPT MCP documentation: https://platform.openai.com/docs/mcp
- `default-project-mode.md` - Required for ChatGPT tools
- `cloud-mode-usage.md` - Deploying MCP to cloud
- Standard MCP tools documentation