# eGain MCP Server

Model Context Protocol (MCP) server for the eGain Knowledge platform — local stdio transport only.

<div align="left">
  <a href="https://opensource.org/licenses/MIT">
    <img src="https://img.shields.io/badge/License-MIT-blue.svg" style="width: 100px; height: 28px;" />
  </a>
</div>

## Overview

This server exposes eGain Knowledge APIs — Portal Manager, Search, Retrieve, and Answers — as a single local MCP endpoint for AI clients. It runs as a child process via stdio, so no server infrastructure is needed.

It enables tools like Claude Desktop, Cursor, and VS Code to:
- Browse and discover knowledge portals
- Search and retrieve articles
- Generate AI-powered answers from your knowledge base
- Submit content suggestions

> This MCP server targets **eGain v4 APIs**. Platform version **21.22 or newer** is required. See the [eGain developer portal](https://apidev.egain.com/) for API details.

## Prerequisites

- **Node.js 20+**
- eGain platform version **21.22 or newer** with AI Services enabled
- A knowledge portal with published content
- A client application in your eGain tenant with delegated permissions:
  - `knowledge.portalmgr.manage`
  - `knowledge.portalmgr.read`
  - `core.aiservices.read`

> **New in 1.1.2:** optional Content Manager authoring tools, off by default. To turn them on, see the [Authoring Guide](./help/authoring.md). It needs two more permissions: `knowledge.contentmgr.read` and `knowledge.contentmgr.manage`.

## Installation

### Quick start with npx (no install needed)

```json
{
  "mcpServers": {
    "eGainMCP": {
      "command": "npx",
      "args": [
        "@egain/egain-mcp-server",
        "start",
        "--api-domain", "your-tenant.egain.cloud",
        "--access-token", "YOUR_ACCESS_TOKEN"
      ]
    }
  }
}
```

### Install globally

```bash
npm install -g @egain/egain-mcp-server
```

Then configure your MCP client:

```json
{
  "mcpServers": {
    "eGainMCP": {
      "command": "mcp",
      "args": [
        "start",
        "--api-domain", "your-tenant.egain.cloud",
        "--access-token", "YOUR_ACCESS_TOKEN"
      ]
    }
  }
}
```

## Configuration

| Flag | Description | Default |
|---|---|---|
| `--api-domain` | Your eGain tenant domain (e.g. `api.ai.egain.cloud`) | — |
| `--access-token` | Bearer token for API authentication | — |
| `--server` | Predefined server alias (`server_0` or `server_1`) | `server_0` |
| `--server-url` | Override the full server URL | — |
| `--tool` | Mount specific tools only (repeatable) | all tools |
| `--tool-annotations` | Filter tools by annotation (`readOnly`, `destructive`, `idempotent`, `openWorld`) | — |
| `--mode dynamic` | Expose `list_tools`/`describe_tool`/`execute_tool` instead of individual tools | — |
| `--log-level` | `debug`, `info`, `warning`, `error` | `info` |

## Available tools

| Tool | Description |
|---|---|
| `get-my-portals` | List portals accessible to the authenticated user |
| `get-all-portals` | List all portals in the partition/department |
| `ai-search` | Hybrid semantic + keyword search across the knowledge base |
| `get-best-answer` | Generate an AI-powered answer for a query |
| `retrieve-chunks` | Retrieve ranked content chunks for RAG pipelines |
| `get-article-by-id` | Fetch a full article by its ID |
| `get-announcement-articles` | Fetch announcement articles for a portal |
| `get-popular-articles` | Fetch the most-viewed articles for a portal |
| `make-suggestion` | Submit a content suggestion to a portal |

## Getting an access token

```bash
npx @egain/egain-mcp-server login
```

This opens a browser-based OAuth flow and writes a token to `.bearer_token` in the current directory.

## Building from source

```bash
git clone https://github.com/eGain/egain-mcp-server
cd egain-mcp-server
npm install
npm run build
```

## License

MIT