svrnty-mcp-server/QUICK-START.md

# CODEX MCP Server - Quick Start

**Get your CODEX knowledge base connected via HTTP in 2 minutes.**

## TL;DR

```bash
# 1. Start CODEX API
cd /home/svrnty/codex/CODEX
dotnet run --project src/Codex.Api
# Listens on http://localhost:5099

# 2. Start CODEX MCP Server (HTTP mode)
cd /home/svrnty/codex/OpenHarbor.MCP.Server
dotnet run --project samples/CodexMcpServer
# Listens on http://localhost:5050

# 3. Test the server
curl http://localhost:5050/health

# 4. List available tools
curl -X POST http://localhost:5050/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":"1"}'
```

## What You Get

6 tools accessible via HTTP for interacting with your CODEX knowledge base:

1. **search_codex** - Semantic search across all documents
2. **get_document** - Retrieve specific document by ID
3. **list_documents** - Browse all documents with pagination
4. **search_by_tag** - Filter by tags
5. **get_document_sections** - Get structured sections
6. **list_tags** - View all available tags

## HTTP Endpoints

**Base URL**: `http://localhost:5050`

- `POST /mcp/invoke` - Main MCP JSON-RPC endpoint
- `GET /health` - Health check endpoint

## Example Tool Calls

Once the server is running, you can call tools via HTTP:

### Search CODEX
```bash
curl -X POST http://localhost:5050/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": "1",
    "params": {
      "name": "search_codex",
      "arguments": {
        "query": "neural networks",
        "maxResults": 5
      }
    }
  }'
```

### Get Document
```bash
curl -X POST http://localhost:5050/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": "2",
    "params": {
      "name": "get_document",
      "arguments": {
        "documentId": "abc123"
      }
    }
  }'
```

### List Tags
```bash
curl -X POST http://localhost:5050/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": "3"
  }'
```

## Architecture (HTTP Mode)

```
┌─────────────────┐
│   MCP Client    │
│ (App/Gateway)   │
└────────┬────────┘
         │ HTTP POST
         │ (JSON-RPC 2.0)
         ▼
┌─────────────────┐
│ CODEX MCP Server│
│  (6 tools)      │
│ Port 5050       │
└────────┬────────┘
         │ HTTP REST
         ▼
┌─────────────────┐
│   CODEX API     │
│ Port 5099       │
└─────────────────┘
```

## Requirements

- .NET 8.0 SDK
- CODEX API running at `http://localhost:5099` (for real data)

## Using with MCP Gateway

For production deployments with load balancing and multiple clients:

```bash
# Terminal 1: Start CODEX API
cd /home/svrnty/codex/CODEX
dotnet run --project src/Codex.Api

# Terminal 2: Start CODEX MCP Server
cd /home/svrnty/codex/OpenHarbor.MCP.Server
dotnet run --project samples/CodexMcpServer

# Terminal 3: Start MCP Gateway
cd /home/svrnty/codex/OpenHarbor.MCP.Gateway
dotnet run --project samples/CodexMcpGateway
# Gateway listens on http://localhost:8080
# Routes requests to http://localhost:5050
```

See [OpenHarbor.MCP.Gateway](../OpenHarbor.MCP.Gateway/README.md) for gateway configuration.

## Troubleshooting

### Health check fails

**Solution:** Verify the server is running:

```bash
curl -v http://localhost:5050/health
```

Expected response:
```json
{"status":"Healthy","service":"MCP Server","timestamp":"..."}
```

### Connection refused errors when using tools

**Solution:** Start CODEX API:

```bash
cd /home/svrnty/codex/CODEX
dotnet run --project src/Codex.Api
```

Verify it's running:
```bash
curl http://localhost:5099/health
```

### Port already in use

**Solution:** Check what's using port 5050:

```bash
lsof -i :5050
```

Stop the conflicting process or configure a different port in `appsettings.json`.

## Testing Without CODEX API

The MCP server works even if CODEX API isn't running - it will return proper error messages:

```bash
curl -X POST http://localhost:5050/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":"1"}'
```

**Expected:** JSON listing all 6 tools (even without CODEX API running)

## Configuration

Edit `samples/CodexMcpServer/appsettings.json`:

```json
{
  "Mcp": {
    "Transport": {
      "Type": "Http",
      "Port": 5050
    },
    "Codex": {
      "ApiBaseUrl": "http://localhost:5099"
    }
  }
}
```

## Next Steps

1. **Full integration guide:** See [INTEGRATION-GUIDE.md](INTEGRATION-GUIDE.md)
2. **Architecture details:** See [README.md](README.md)
3. **Gateway setup:** See [OpenHarbor.MCP.Gateway](../OpenHarbor.MCP.Gateway/README.md)
4. **Development:** See [docs/module-design.md](docs/module-design.md)

---

## Legacy Support: Claude Desktop (Stdio Mode)

For local Claude Desktop integration, stdio mode is still available:

```bash
# Run in stdio mode
dotnet run --project samples/CodexMcpServer -- --stdio
```

**Claude Desktop Configuration** (`~/.claude/config.json`):
```json
{
  "mcpServers": {
    "codex": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "/home/svrnty/codex/OpenHarbor.MCP.Server/samples/CodexMcpServer/CodexMcpServer.csproj",
        "--",
        "--stdio"
      ],
      "transport": "stdio"
    }
  }
}
```

**Note**: HTTP mode is recommended for production deployments. Stdio mode is for local development and Claude Desktop integration only.

---

## Files Reference

| File | Purpose |
|------|---------|
| `QUICK-START.md` | This file (2-minute HTTP setup) |
| `INTEGRATION-GUIDE.md` | Detailed integration patterns |
| `README.md` | Complete documentation |
| `HTTP-TRANSPORT-STANDARDIZATION.md` | HTTP architecture guide |

## Support

- Issues: [GitHub Issues](https://github.com/yourusername/OpenHarbor.MCP/issues)
- MCP Spec: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- HTTP Transport Guide: See `HTTP-TRANSPORT-STANDARDIZATION.md`