# MCP-KD Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server for managing [OpenText Knowledge Discovery](https://www.opentext.com/products/knowledge-discovery) content engines. 

This server exposes Content Engine administration tasks as MCP tools, allowing AI assistants to create databases, delete databases, list databases, delete documents, query engine status, and manage engine configuration — all through natural language.

---

## Features

- Pure Python 3.10+ — no external MCP SDK required (JSON-RPC 2.0 over stdio)
- Multi-engine support with an active engine concept
- Hot-reload configuration at runtime
- HTTPS with custom CA bundle support
- Docker-ready (see Docker section below)

## Available Tools

| Tool | Description | Required Params | Optional Params |
|---|---|---|---|
| `create_database` | Create a new database via `DRECREATEDBASE` | `db_name` | `engine_name`, `internal`, `read_only` |
| `delete_database` | Delete a database and all its documents via `DREREMOVEDBASE` | `db_name` | `engine_name`, `ignore_max_pending_items`, `index_uid`, `no_archive`, `priority` |
| `list_databases` | List all databases via `GetStatus` admin action | — | `engine_name` |
| `delete_documents` | Delete all documents from a database via `DREREMOVEDBASE` | `db_name` | `engine_name` |
| `get_status` | Get engine status (version, ports, components) | — | `engine_name` |
| `list_engines` | Show all configured engines and the active one | — | — |
| `reload_config` | Hot-reload `config.json` without restarting | — | — |

---

## Quick Start

### Prerequisites

- Python 3.10 or later
- `httpx` package (`pip install httpx`)
- Access to a running OpenText Knowledge Discovery content engine with HTTPS

### 1. Clone & Configure

```bash
git clone <repo-url>
cd mcp-kd
```

Copy the example config and edit it with your engine details:

```bash
cp config.json.example config.json
```

Edit `config.json`:

```json
{
  "active": "content1",
  "engines": {
    "content1": {
      "host": "content-engine-host.example.com",
      "index_port": 9101,
      "aci_port": 9000,
      "ssl_cert": "/certs/bundle.crt",
      "verify_ssl": true
    }
  },
  "request_timeout": 30,
  "log_level": "INFO"
}
```

| Key | Description |
|---|---|
| `active` | Which engine entry is used by default |
| `engines.<name>.host` | Hostname or IP of the content engine |
| `engines.<name>.index_port` | Index action port (e.g., `DRECREATEDBASE`) |
| `engines.<name>.aci_port` | ACI / admin action port (e.g., `GetStatus`) |
| `engines.<name>.ssl_cert` | Path to the CA certificate bundle for HTTPS |
| `engines.<name>.verify_ssl` | Set to `false` to skip SSL verification (not recommended) |
| `request_timeout` | HTTP request timeout in seconds |
| `log_level` | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |

### 2. Install Dependencies

```bash
pip install httpx>=0.27.0
```

If using a virtual environment:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### 3. Prepare SSL Certificate

Place your content engine's CA certificate bundle at the path specified in `config.json` (`ssl_cert`):

```bash
mkdir -p certs
cp /path/to/your/bundle.crt certs/
```

### 4. Run the Server

```bash
python3 server.py
```

The server listens on **stdin/stdout** using the MCP JSON-RPC 2.0 protocol. It is designed to be launched by an MCP host (VS Code, Claude Desktop, etc.).

---

## VS Code Integration

Add this to `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "mcp-kd": {
      "command": "/usr/bin/python3",
      "args": ["/path/to/mcp-kd/server.py"],
      "env": { "PYTHONUNBUFFERED": "1" }
    }
  }
}
```

Reload the VS Code window (`Developer: Reload Window`) and `mcp-kd` will appear in the MCP Servers view.

---

## Docker

### Build

```bash
docker build -t mcp-kd:latest .
```

### Run with Docker Compose

```bash
docker compose up -d
```

The `docker-compose.yml` mounts `config.json` and the `certs/` directory as volumes so you can update them without rebuilding the image.

### Run with Docker CLI

```bash
docker run -i \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v $(pwd)/certs:/certs:ro \
  mcp-kd:latest
```

The `-i` flag (stdin open) is **required** — MCP communicates via stdio.

---

## Architecture

```
┌──────────────┐     stdio/JSON-RPC      ┌──────────────┐     HTTPS/REST     ┌─────────────────┐
│  MCP Host    │ ◄──────────────────────► │  server.py   │ ◄────────────────► │  Content Engine │
│ (VS Code,    │                          │  (MCP-KD)    │                    │  (OpenText KD)  │
│  Claude, etc)│                          └──────┬───────┘                    └─────────────────┘
└──────────────┘                                 │
                                          ┌──────▼───────┐
                                          │ content_engine.py │
                                          │ (REST client)     │
                                          └──────────────────┘
```

- **`server.py`** — MCP protocol layer: parses JSON-RPC requests, routes to tool handlers, returns responses
- **`content_engine.py`** — REST API client: manages HTTPS connections, maps tool calls to Content Engine index/admin actions

---

## Multi-Engine Support

Define multiple engines in `config.json` and switch between them at runtime by providing the `engine_name` parameter in tool calls:

```json
{
  "active": "content1",
  "engines": {
    "content1": { "host": "engine1.example.com", "index_port": 9101, "aci_port": 9000 },
    "content2": { "host": "engine2.example.com", "index_port": 9101, "aci_port": 9000 }
  }
}
```

Pass `"engine_name": "content2"` to target a specific engine. Omit it to use the `active` engine.

---

## Project Structure

```
mcp-kd/
├── server.py              # MCP server (JSON-RPC 2.0 over stdio)
├── content_engine.py      # Content Engine REST API client
├── config.json            # Engine configuration (git-ignored)
├── config.json.example    # Example config with placeholder values
├── requirements.txt       # Python dependencies
├── Dockerfile             # Docker image definition
├── docker-compose.yml     # Docker Compose configuration
├── .gitignore             # Git ignore rules
├── .dockerignore          # Docker build ignore rules
├── test_smoke.py          # Smoke test for the MCP server
├── instructions/          # Reference docs for Content Engine actions
│   ├── goal.md
│   ├── createDb.md
│   ├── deleteDb.md
│   ├── getstatus.md
│   └── general-instructions.md
└── certs/                 # SSL certificate bundles (git-ignored)
    └── bundle.crt
```

---

## License

This project is provided as-is for managing OpenText Knowledge Discovery content engines.