@cliniq360/eigi-mcp 1.0.0

package/README.md

@@ -0,0 +1,718 @@
+# eigi.ai MCP Server
+
+[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://github.com/modelcontextprotocol/registry)
+[![npm version](https://img.shields.io/npm/v/@cliniq360/eigi-mcp)](https://www.npmjs.com/package/@cliniq360/eigi-mcp)
+
+MCP (Model Context Protocol) server for [eigi.ai](https://eigi.ai) - enabling AI-native integration with your AI voice and chat agents through Claude Desktop and other MCP-compatible clients.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Installation Options](#installation-options)
+- [MCP Registry](#mcp-registry)
+- [Configuration](#configuration)
+- [Claude Desktop Setup](#claude-desktop-setup)
+- [Commands](#commands)
+- [API Endpoints](#api-endpoints)
+- [MCP Tools Reference](#mcp-tools-reference)
+- [MCP Resources (UI)](#mcp-resources-ui)
+- [Project Structure](#project-structure)
+- [Docker](#docker)
+- [Authentication](#authentication)
+- [Publishing](#publishing)
+
+## Features
+
+- **20+ MCP Tools** for managing agents, conversations, calls, chats, and prompts
+- **5 UI Resources** for rich interactive experiences
+- **Real-time Voice Testing** via Pipecat AI integration
+- **Dual Transport Support** - Remote (HTTP) and Local (stdio) modes
+- **Hot-reload Development** with Vite and tsx watchers
+- **TypeScript** for type safety
+- **Tailwind CSS 4** for modern UI styling
+
+## Quick Start
+
+### Get Your API Key
+
+1. Sign up at [eigi.ai](https://eigi.ai)
+2. Navigate to Settings → API Keys
+3. Generate a new API key
+
+### Connect via Remote Server (Fastest)
+
+Add to your Claude Desktop config - no installation required:
+
+```json
+{
+  "mcpServers": {
+    "eigi": {
+      "url": "https://mcp.eigi.ai/mcp",
+      "transport": "streamable-http",
+      "headers": {
+        "X-API-Key": "YOUR_EIGI_API_KEY"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Installation Options
+
+### Option 1: Remote Server (Recommended)
+
+Connect directly to the hosted eigi.ai MCP server. **No installation required.**
+
+**Supported authentication methods:**
+- Header: `X-API-Key: YOUR_KEY`
+- Header: `Authorization: Bearer YOUR_KEY`
+- Query parameter: `?api_key=YOUR_KEY`
+
+### Option 2: Local via npm
+
+Install and run locally:
+
+```bash
+# Using npx (no install)
+EIGI_API_KEY=your-key npx @cliniq360/eigi-mcp --stdio
+
+# Or install globally
+npm install -g @cliniq360/eigi-mcp
+EIGI_API_KEY=your-key eigi-mcp --stdio
+```
+
+### Option 3: From Source (Development)
+
+```bash
+# Clone the repository
+git clone https://github.com/eigi-ai/eigi-mcp.git
+cd eigi-mcp/eigi-app
+
+# Install dependencies
+npm install
+
+# Copy environment file
+cp .env.example .env
+
+# Run development server
+npm run dev
+```
+
+---
+
+## MCP Registry
+
+This server is published to the [MCP Registry](https://github.com/modelcontextprotocol/registry) as:
+
+```
+io.github.eigi-ai/eigi
+```
+
+| Mode | Transport | Endpoint |
+|------|-----------|----------|
+| **Remote** | streamable-http | `https://mcp.eigi.ai/mcp` |
+| **Local** | stdio | `npx @cliniq360/eigi-mcp --stdio` |
+
+---
+
+## Claude Desktop Setup
+
+### Remote Mode (Recommended)
+
+No installation needed. Edit `claude_desktop_config.json`:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "eigi": {
+      "url": "https://mcp.eigi.ai/mcp",
+      "transport": "streamable-http",
+      "headers": {
+        "X-API-Key": "YOUR_EIGI_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### Local Mode (stdio)
+
+For offline use or custom deployments:
+
+```json
+{
+  "mcpServers": {
+    "eigi": {
+      "command": "npx",
+      "args": ["-y", "@cliniq360/eigi-mcp", "--stdio"],
+      "env": {
+        "EIGI_API_KEY": "YOUR_EIGI_API_KEY"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `EIGI_API_KEY` | Your eigi.ai API key | - | **Yes** (stdio mode) |
+| `EIGI_API_BASE_URL` | Backend API URL | `https://prod.eigi.ai` | No |
+| `VITE_EIGI_API_BASE_URL` | API URL for browser builds | `https://prod.eigi.ai` | No |
+| `PORT` | Server port (HTTP mode) | `3001` | No |
+
+### Environment File (Development)
+
+```bash
+cp .env.example .env
+```
+
+```env
+# Your eigi.ai API key (required for stdio mode)
+EIGI_API_KEY=your-api-key-here
+
+# API Base URL
+EIGI_API_BASE_URL=https://prod.eigi.ai
+
+# Browser builds
+VITE_EIGI_API_BASE_URL=https://prod.eigi.ai
+
+# MCP Server Port
+PORT=3001
+```
+
+---
+
+## Commands
+
+### Quick Reference
+
+| Command | Description |
+|---------|-------------|
+| `npm install` | Install dependencies |
+| `npm run dev` | Development mode with hot-reload |
+| `npm run build` | Build for production (HTTP server) |
+| `npm run build:npm` | Build for npm package (stdio) |
+| `npm run serve` | Start HTTP server |
+| `npm run serve:stdio` | Start stdio server |
+| `npm run start` | Build + serve HTTP |
+| `npm run start:stdio` | Build + serve stdio |
+
+### Helper Script
+
+```bash
+# Make executable
+chmod +x start.sh
+
+# Run commands
+./start.sh dev      # Development mode
+./start.sh stdio    # stdio mode
+./start.sh http     # HTTP server mode
+./start.sh build    # Production build
+```
+
+### Detailed Command Reference
+
+#### `npm run dev` - Development Mode
+
+Starts the development server with hot-reload. Runs **6 concurrent processes**:
+
+```bash
+npm run dev
+
+# What it runs:
+# 1. vite build --watch (conversations-app.html)
+# 2. vite build --watch (conversations-list-app.html)
+# 3. vite build --watch (conversation-detail-app.html)
+# 4. vite build --watch (agents-app-v2.html)
+# 5. vite build --watch (interactive-agent-v2.html)
+# 6. tsx --watch main.ts (server with hot-reload)
+```
+
+**Output:**
+
+- Server runs at `http://localhost:3001`
+- MCP endpoint at `http://localhost:3001/mcp`
+- All file changes trigger automatic rebuild
+
+#### `npm run build` - Production Build
+
+Compiles TypeScript and builds all UI apps:
+
+```bash
+npm run build
+
+# What it does:
+# 1. tsc --noEmit (TypeScript type checking only)
+# 2. Builds conversations-app.html → dist/
+# 3. Builds conversations-list-app.html → dist/
+# 4. Builds conversation-detail-app.html → dist/
+# 5. Builds agents-app-v2.html → dist/
+# 6. Builds interactive-agent-v2.html → dist/
+```
+
+**Output:**
+
+- Creates `dist/` folder with compiled assets
+- Each HTML page becomes a single-file bundle (via vite-plugin-singlefile)
+
+#### `npm run build:npm` - Build for npm Package
+
+Compiles server-side code for stdio mode (npm package):
+
+```bash
+npm run build:npm
+
+# What it does:
+# 1. Compiles TypeScript using tsconfig.build.json
+# 2. Outputs to dist/ (server code only, no UI)
+```
+
+#### `npm run serve:stdio` - stdio Mode
+
+Runs the MCP server in stdio mode (for local MCP clients):
+
+```bash
+npm run serve:stdio
+
+# Or with environment variable:
+EIGI_API_KEY=your-key npm run serve:stdio
+```
+
+#### `npm run serve` - Start Server
+
+Starts the MCP server in production mode:
+
+```bash
+npm run serve
+
+# What it runs:
+# tsx main.ts
+```
+
+**Note:** Requires `npm run build` to be run first.
+
+#### `npm run start` - Full Production Start
+
+Builds and then starts the server:
+
+```bash
+npm run start
+
+# Equivalent to:
+# npm run build && npm run serve
+```
+
+---
+
+## Usage Examples
+
+### Starting Development
+
+```bash
+# 1. Install dependencies (first time only)
+npm install
+
+# 2. Configure environment
+cp .env.example .env
+# Edit .env with your API URL
+
+# 3. Start development server
+npm run dev
+
+# Server is now running at http://localhost:3001
+# MCP endpoint: http://localhost:3001/mcp
+```
+
+### Production Deployment
+
+```bash
+# 1. Build production assets
+npm run build
+
+# 2. Start server
+npm run serve
+
+# Or do both in one command
+npm run start
+```
+
+### Testing MCP Endpoint
+
+```bash
+# Health check
+curl http://localhost:3001/health
+# Response: {"status":"ok"}
+
+# Welcome endpoint
+curl http://localhost:3001/
+# Response: Welcome to eigi.ai MCP
+
+# MCP endpoint (requires proper JSON-RPC request)
+curl -X POST http://localhost:3001/mcp \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+---
+
+## API Endpoints
+
+| Endpoint  | Method | Description                                |
+| --------- | ------ | ------------------------------------------ |
+| `/`       | GET    | Welcome message (`Welcome to eigi.ai MCP`) |
+| `/health` | GET    | Health check (`{"status": "ok"}`)          |
+| `/mcp`    | ALL    | MCP protocol endpoint (JSON-RPC 2.0)       |
+| `/log`    | POST   | Browser logging endpoint                   |
+
+### Health Check Example
+
+```bash
+curl http://localhost:3001/health
+```
+
+Response:
+
+```json
+{ "status": "ok" }
+```
+
+---
+
+## MCP Tools Reference
+
+### Conversations
+
+| Tool                 | Description                                                                         |
+| -------------------- | ----------------------------------------------------------------------------------- |
+| `list-conversations` | List voice and chat conversations with filters (page, status, date range, agent_id) |
+| `get-conversation`   | Get full conversation details including transcript and analysis                     |
+
+### Agents
+
+| Tool               | Description                                         |
+| ------------------ | --------------------------------------------------- |
+| `list-agents`      | List AI voice agents with pagination                |
+| `get-agent`        | Get agent details and configuration by ID           |
+| `create-agent`     | Create a new AI voice agent with STT/LLM/TTS config |
+| `update-agent`     | Update an existing agent's settings                 |
+| `delete-agent`     | Delete an agent by ID                               |
+| `test-voice-agent` | Open interactive UI to test an agent in real-time   |
+
+### Calls
+
+| Tool                     | Description                                       |
+| ------------------------ | ------------------------------------------------- |
+| `initiate-outbound-call` | Initiate an outbound voice call using an AI agent |
+| `get-mobile-numbers`     | Get available mobile numbers for agents           |
+
+### Chat
+
+| Tool                      | Description                                    |
+| ------------------------- | ---------------------------------------------- |
+| `list-chat-sessions`      | List text chat sessions with pagination        |
+| `get-chat-session`        | Get complete chat session with all messages    |
+| `send-chat-message`       | Send a message to an AI agent and get response |
+| `get-agent-first-message` | Get agent's greeting/intro message             |
+
+### Prompts
+
+| Tool                  | Description                                       |
+| --------------------- | ------------------------------------------------- |
+| `list-prompts`        | List prompts with pagination                      |
+| `get-prompt`          | Get a prompt by name (latest or specific version) |
+| `get-prompt-versions` | Get version history for a prompt                  |
+| `create-prompt`       | Create a new prompt (or new version if exists)    |
+| `update-prompt`       | Update an existing prompt                         |
+
+### Providers
+
+| Tool             | Description                                                           |
+| ---------------- | --------------------------------------------------------------------- |
+| `list-providers` | List available LLM, TTS, and STT providers with their models          |
+| `list-voices`    | List available voices for a TTS provider (CARTESIA, ELEVENLABS, etc.) |
+
+---
+
+## MCP Resources (UI)
+
+Rich UI resources for enhanced interaction within MCP clients:
+
+| Resource URI                                            | Description                         |
+| ------------------------------------------------------- | ----------------------------------- |
+| `ui://conversations/conversations-app.html`             | Main conversations dashboard        |
+| `ui://conversations-list/conversations-list-app.html`   | Conversations list view             |
+| `ui://conversation-detail/conversation-detail-app.html` | Conversation detail with transcript |
+| `ui://agents/agents-app-v2.html`                        | Agents management interface         |
+| `ui://interactive-agent/interactive-agent-v2.html`      | Interactive agent testing widget    |
+
+---
+
+## Project Structure
+
+```
+eigi-app/
+├── main.ts                   # Server entry point (Express + MCP)
+├── server.ts                 # MCP server configuration and tool registration
+├── package.json              # Dependencies and npm scripts
+├── tsconfig.json             # TypeScript configuration
+├── vite.config.ts            # Vite build configuration
+├── Dockerfile                # Docker image definition
+├── .env.example              # Environment template
+│
+├── pages/                    # HTML entry points for UI apps
+│   ├── agents-app-v2.html
+│   ├── conversations-app.html
+│   ├── conversations-list-app.html
+│   ├── conversation-detail-app.html
+│   └── interactive-agent-v2.html
+│
+├── dist/                     # Built output (generated by npm run build)
+│
+└── src/
+    ├── index.ts              # Main exports
+    ├── global.css            # Global styles
+    │
+    ├── api/                  # API client for eigi.ai backend
+    │   ├── client.ts         # HTTP client with auth handling
+    │   └── index.ts
+    │
+    ├── apps/                 # React application entry points
+    │   ├── agents-app.tsx
+    │   ├── conversations-app.tsx
+    │   ├── conversations-list-app.tsx
+    │   ├── conversation-detail-app.tsx
+    │   └── interactive-agent-app.tsx
+    │
+    ├── components/           # Shared React components
+    │   ├── VoiceCallDialog.tsx
+    │   ├── VoiceCallUI.tsx
+    │   ├── VoiceCallUI.module.css
+    │   └── ui/               # UI primitives
+    │       ├── avatar.tsx
+    │       ├── badge.tsx
+    │       ├── button.tsx
+    │       ├── card.tsx
+    │       └── index.ts
+    │
+    ├── config/               # Configuration constants
+    │   ├── constants.ts      # API URLs, resource URIs, enums
+    │   └── index.ts
+    │
+    ├── lib/                  # Utility functions
+    │   └── utils.ts          # cn() for class merging
+    │
+    ├── resources/            # MCP resource registrations
+    │   ├── agents.ts
+    │   ├── conversations.ts
+    │   ├── conversations-list.ts
+    │   ├── conversation-detail.ts
+    │   ├── interactive-agent.ts
+    │   └── index.ts
+    │
+    ├── tools/                # MCP tool implementations
+    │   ├── agents.ts         # Agent CRUD tools
+    │   ├── calls.ts          # Outbound call tools
+    │   ├── chat.ts           # Chat session tools
+    │   ├── conversations.ts  # Conversation list/detail tools
+    │   ├── interactive-agent.ts
+    │   ├── prompts.ts        # Prompt management tools
+    │   ├── providers.ts      # Provider/voice listing tools
+    │   ├── base.ts           # Shared utilities
+    │   └── index.ts
+    │
+    ├── types/                # TypeScript type definitions
+    │   ├── agent.ts
+    │   ├── api.ts
+    │   ├── calls.ts
+    │   ├── chat-session.ts
+    │   ├── conversation.ts
+    │   └── index.ts
+    │
+    └── utils/                # Logging utilities
+        ├── browser-logger.ts # Browser-side logging
+        └── logger.ts         # Server-side logging
+```
+
+---
+
+## Docker
+
+### Build and Run
+
+```bash
+# Build Docker image
+docker build -t eigi-app .
+
+# Build with custom API URL
+docker build \
+  --build-arg VITE_EIGI_API_BASE_URL=https://prod.eigi.ai \
+  -t eigi-app .
+
+# Run container
+docker run -p 7500:7500 --env-file .env eigi-app
+
+# Run with environment variables inline
+docker run -p 7500:7500 \
+  -e EIGI_API_BASE_URL=https://prod.eigi.ai \
+  -e PORT=7500 \
+  eigi-app
+```
+
+### Dockerfile Overview
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+
+# Build arg for Vite (embedded at build time)
+ARG VITE_EIGI_API_BASE_URL=https://prod.qa.eigi.ai
+ENV VITE_EIGI_API_BASE_URL=$VITE_EIGI_API_BASE_URL
+
+COPY package*.json .
+RUN npm install
+COPY . .
+RUN npm run build
+EXPOSE 7500
+CMD ["npm", "run", "serve"]
+```
+
+---
+
+## Authentication
+
+### Remote Mode (HTTP)
+
+The MCP server extracts API keys from requests in the following priority order:
+
+1. **Authorization Header**: `Authorization: Bearer <token>`
+2. **X-API-Key Header**: `X-API-Key: <token>`
+3. **Query Parameter**: `?api_key=<token>`
+
+### Local Mode (stdio)
+
+API key is passed via environment variable:
+
+```bash
+EIGI_API_KEY=your-key npx @cliniq360/eigi-mcp --stdio
+```
+
+Or in Claude Desktop config:
+```json
+{
+  "env": {
+    "EIGI_API_KEY": "your-key"
+  }
+}
+```
+
+### Example Requests (HTTP)
+
+```bash
+# Using Authorization header (recommended)
+curl -X POST http://localhost:3001/mcp \
+  -H "Authorization: Bearer your-api-key-here" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+
+# Using X-API-Key header
+curl -X POST http://localhost:3001/mcp \
+  -H "X-API-Key: your-api-key-here" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+
+# Using query parameter
+curl -X POST "http://localhost:3001/mcp?api_key=your-api-key-here" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+---
+
+## Tech Stack
+
+| Category       | Technology                | Version |
+| -------------- | ------------------------- | ------- |
+| **Runtime**    | Node.js                   | 20+     |
+| **Server**     | Express.js                | 5.x     |
+| **MCP SDK**    | @modelcontextprotocol/sdk | 1.24+   |
+| **Frontend**   | React                     | 19.x    |
+| **Build Tool** | Vite                      | 6.x     |
+| **Styling**    | Tailwind CSS              | 4.x     |
+| **Voice**      | Pipecat AI + Daily        | 1.x     |
+| **Validation** | Zod                       | 4.x     |
+| **Language**   | TypeScript                | 5.9+    |
+
+---
+
+## Publishing
+
+### npm Package
+
+The package is published as `@cliniq360/eigi-mcp` via GitHub Actions.
+
+**Automated Publishing:**
+1. Update version in `package.json`
+2. Commit changes
+3. Create a git tag: `git tag v1.0.0`
+4. Push tag: `git push origin v1.0.0`
+5. GitHub Actions automatically publishes to npm
+
+**Manual Publishing (if needed):**
+```bash
+# Build for npm
+npm run build:npm
+
+# Publish (requires npm auth)
+npm publish --access public
+```
+
+### MCP Registry
+
+The server is registered with:
+- **Registry Name**: `io.github.eigi-ai/eigi`
+- **npm Package**: `@cliniq360/eigi-mcp`
+
+Configuration is in `server.json`:
+```json
+{
+  "mcpName": "io.github.eigi-ai/eigi",
+  "remotes": {
+    "streamable-http": {
+      "transportType": "streamable-http",
+      "url": "https://mcp.eigi.ai/mcp"
+    }
+  },
+  "packages": {
+    "npm": {
+      "name": "@cliniq360/eigi-mcp",
+      "transportType": "stdio"
+    }
+  }
+}
+```
+
+### GitHub Actions Workflow
+
+The `.github/workflows/publish-mcp.yml` workflow:
+- Triggers on `v*` tags
+- Uses OIDC for npm provenance
+- Builds and publishes to npm registry
+- Adds to MCP Registry automatically
+
+---
+
+## License
+
+Proprietary - © ClinIQ360

package/dist/main.d.ts

@@ -0,0 +1,5 @@
+import "dotenv/config";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function startStreamableHTTPServer(factory: (apiKey?: string) => McpServer): Promise<void>;
+export declare function startStdioServer(factory: (apiKey?: string) => McpServer): Promise<void>;
+//# sourceMappingURL=main.d.ts.map