# DealHub Admin MCP Server

Model Context Protocol (MCP) server for DealHub administrators. Manage versions through Claude and other AI agents using natural language.

## Features

The DealHub Admin MCP provides 5 tools for version management:

### 🔍 Query Tools
- **`list_versions`** - List all versions with optional status filter (ACTIVE, DRAFT, DEACTIVATED)
- **`get_version`** - Get details of a specific version by ID or name
- **`get_active_version`** - Get the currently active version

### ⚡ Action Tools
- **`activate_version`** - Activate a version (async operation)
- **`duplicate_version`** - Duplicate a version with a new name (async operation)

## Prerequisites

- Node.js 18.0.0 or higher
- DealHub admin account with API token

## Setup

### 1. Generate API Token

1. Log in to DealHub as an admin
2. Navigate to **Settings** → **Integrations** → **Partner API**
3. Click **Generate Token**
4. Copy the `clientId` and `clientSecret`

### 2. Install Dependencies

```bash
cd mcp-servers/dealhub-admin
npm install
```

### 3. Configure Environment

Create a `.env` file:

```bash
cp .env.example .env
```

Edit `.env` and add your credentials:

```env
DEALHUB_API_BASE_URL=https://app.dealhub.io
DEALHUB_API_TOKEN=your-client-id:your-client-secret
```

**Important:** Replace `your-client-id` and `your-client-secret` with actual values from step 1.

### 4. Build the Server

```bash
npm run build
```

### 5. Configure Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "dealhub-admin": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-servers/dealhub-admin/dist/index.js"],
      "env": {
        "DEALHUB_API_BASE_URL": "https://app.dealhub.io",
        "DEALHUB_API_TOKEN": "your-client-id:your-client-secret"
      }
    }
  }
}
```

**Replace `/absolute/path/to/` with the actual path to your project.**

### 6. Restart Claude Desktop

Quit and restart Claude Desktop for changes to take effect.

## Usage

### Example Natural Language Commands

Once configured, you can use natural language with Claude:

**List versions:**
- "Show me all versions"
- "List all draft versions"
- "What active versions do we have?"

**Get version details:**
- "Get details for version ABC123"
- "Show me the version named 'Q1 2026'"

**Check active version:**
- "Which version is currently active?"
- "What's the active version?"

**Activate a version:**
- "Activate version ABC123"
- "Make version XYZ the active version"

**Duplicate a version:**
- "Duplicate version ABC123 as 'Q2 2026'"
- "Copy version ABC123 and name it 'Test Version'"

## Tool Details

### list_versions

**Parameters:**
- `status` (optional): Filter by status - `"ACTIVE"`, `"DRAFT"`, or `"DEACTIVATED"`

**Example:**
```json
{
  "status": "DRAFT"
}
```

**Response:**
```json
[
  {
    "id": "abc123-def456",
    "name": "Q1 2026",
    "status": "DRAFT",
    "created": "2025-01-15T10:30:00Z"
  }
]
```

### get_version

**Parameters:**
- `versionId` (string): Version GUID - OR -
- `versionName` (string): Version name

**Note:** Provide either `versionId` OR `versionName`, not both.

**Example:**
```json
{
  "versionId": "abc123-def456"
}
```

**Response:**
```json
{
  "guid": "abc123-def456",
  "name": "Q1 2026",
  "status": "DRAFT",
  "createdDate": "2025-01-15T10:30:00Z",
  "comparedToVersionGuid": "xyz789"
}
```

### get_active_version

**Parameters:** None

**Response:**
```json
{
  "guid": "xyz789-uvw012",
  "name": "Production 2025",
  "status": "ACTIVE",
  "createdDate": "2024-12-01T08:00:00Z"
}
```

Or if no active version:
```
No active version found
```

### activate_version

**Parameters:**
- `versionId` (required): Version GUID to activate
- `content` (optional): Email content for activation notification
- `subject` (optional): Email subject for activation notification

**Example:**
```json
{
  "versionId": "abc123-def456",
  "subject": "New version activated",
  "content": "Q1 2026 version is now active"
}
```

**Response:**
```
Version activation started. Request ID: req-789xyz
Status: PENDING
```

**Note:** This is an async operation. The version activation happens in the background. Use the request ID to track progress if needed.

### duplicate_version

**Parameters:**
- `versionId` (required): Source version GUID to duplicate
- `newName` (required): Name for the duplicated version

**Example:**
```json
{
  "versionId": "abc123-def456",
  "newName": "Q2 2026"
}
```

**Response:**
```
Version duplication started. Request ID: req-456abc
Status: PENDING
```

**Note:** This is an async operation. The version duplication happens in the background. Use the request ID to track progress if needed.

### resolve_quote

Advances the **stateless quote resolve loop** one turn. You submit answers, the server re-evaluates the whole playbook (visibility, defaults, mandatory checks) and returns the next questions plus an opaque `state` blob. The server keeps nothing between turns — thread `state` back in on every call.

**Parameters:**
- `opportunityGuid` (required): CRM opportunity GUID to bind to
- `playbookGuid`: required on the first turn (when no `state`); afterward read from the blob
- `state`: opaque base64+gzip blob from the previous response — omit on turn 1
- `newAnswers`: map of attribute path → typed value (e.g. `{ "Sizing.NumUsers": 50 }`)
- `newProducts`, `versionGuid`, `resolveDefaults`, `runExternalQueries`, `includeResolvedForm`, `crmParams`, `tracePaths`: optional

**Loop:** turn 1 with `{ opportunityGuid, playbookGuid }` → feed `state` back with `newAnswers` each turn → stop when `ready_to_finalize` is `true`.

> ⚠️ **Host availability.** This endpoint only exists on DealHub backends that have the resolve loop deployed (currently dev backends, e.g. `http://localhost:9000`). Against a host that lacks it — including production hosts like `service-us1.dealhub.io` — the API returns its HTML 404 page and the tool reports *"Endpoint not available on this host."* Point `DEALHUB_API_BASE_URL` at a backend that serves it.

### finalize_quote

Finalizes a quote from a resolved state — a terminal resolve pass that persists a **Draft** quote. Call once `resolve_quote` reports `ready_to_finalize: true`, passing the latest `state` blob. Identity (opportunity / playbook / version) and all answers come from the blob; the only required field is `state`. Optional overrides: `quoteName`, `docType` (PDF / WORD / EXCEL / DealHub), `outputDocumentGUID`, `proposalExpiration` (epoch millis).

Returns the created quote — `quote_guid`, `quote_num`, `quote_name`, `identifier`, and `status` (`Draft`). If mandatory answers are still missing, the API returns `422` with `missing_mandatory` listing the unanswered paths.

## Development

### Run in Development Mode

```bash
npm run dev
```

### Rebuild After Changes

```bash
npm run build
```

### Clean Build Artifacts

```bash
npm run clean
```

## Architecture

The MCP server uses DealHub's existing OpenAPI endpoints with `ByApiToken` authentication:

- **Authentication:** `webserver/app/com/valooto/api/auth/ByApiToken.java`
- **Version API:** `webserver/app/controllers/openApi/OpenAPIVersionController.java`
- **API Routes:** `webserver/conf/api.routes`

### API Endpoints Used

| Tool | HTTP Method | Endpoint | Controller Method |
|------|-------------|----------|-------------------|
| list_versions | GET | `/v1/versions` | `getVersions()` (line 590) |
| get_version | GET | `/v1/version/id/:id` | `getVersionById()` (line 669) |
| get_version | GET | `/v1/version/name/:name` | `getVersionByName()` (line 633) |
| get_active_version | GET | `/v1/versions?status=ACTIVE` | `getVersions()` (line 590) |
| activate_version | POST | `/v1/version/activate` | `activateVersion()` (line 766) |
| duplicate_version | POST | `/v1/version/duplicate` | `duplicateVersion()` (line 703) |
| resolve_quote | POST | `/v1/quote/resolve` | `OpenAPIQuoteResolverController.resolve` |
| finalize_quote | POST | `/v1/quote/finalize` | `OpenAPIHeadlessProposalController` |

> The quote resolve-loop endpoints (`/v1/quote/resolve`, `/v1/quote/finalize`) are only available on backends where that loop is deployed.

## Troubleshooting

### "Authentication failed"

- Verify your token is correct in `.env`
- Ensure token format is `clientId:clientSecret`
- Check that your admin user has API access enabled

### "No response from DealHub API"

- Verify `DEALHUB_API_BASE_URL` is correct
- Check your internet connection
- Ensure DealHub is accessible

### MCP server not appearing in Claude

- Verify the path in `claude_desktop_config.json` is absolute (not relative)
- Check that `dist/index.js` exists (run `npm run build`)
- Restart Claude Desktop completely
- Check Claude Desktop logs: `~/Library/Logs/Claude/`

### TypeScript compilation errors

```bash
npm run clean
npm install
npm run build
```

## Security

- **Never commit `.env` files** - They contain your API credentials
- **Token permissions** - Tokens have the same permissions as the admin user who generated them
- **Rotate tokens** - Regularly regenerate API tokens for security

## Privacy Policy

### Data Collection
The DealHub Admin MCP Server does **not** collect, store, or transmit any user data except as necessary to communicate with your DealHub instance.

### Data Accessed
This MCP server accesses the following data from your DealHub instance:
- Version metadata (names, IDs, statuses, creation dates)
- Active version information
- Version activation and duplication results

### Data Storage
- **API Credentials**: Your DealHub API token (clientId and clientSecret) is stored locally in a `.env` file on your machine. This file never leaves your computer.
- **No Remote Storage**: This MCP server does not store any data on remote servers. All operations are performed locally on your machine.
- **No Analytics**: No usage analytics, telemetry, or tracking data is collected.

### Data Transmission
- **DealHub API Only**: API calls are made exclusively to your configured DealHub instance (`DEALHUB_API_BASE_URL`).
- **HTTPS Encryption**: All API communications use HTTPS for encryption in transit.
- **No Third Parties**: No data is shared with or transmitted to any third-party services.

### User Controls
- You have complete control over your API credentials stored in the `.env` file
- You can revoke API tokens at any time through the DealHub admin interface
- Deleting the `.env` file removes all stored credentials

### Data Retention
- The MCP server retains no data between sessions
- API credentials persist only in your local `.env` file until you delete them
- No logs or historical data are stored

## Data Handling Practices

### How Your Data is Used
1. **Authentication**: Your API token is used to authenticate requests to the DealHub API
2. **Version Management**: Version data retrieved from DealHub is displayed to you through Claude
3. **Temporary Processing**: Data is processed in memory during tool execution and discarded immediately after

### What We Don't Do
- ❌ Store conversation history
- ❌ Log API requests or responses
- ❌ Share data with third parties
- ❌ Use data for training or analytics
- ❌ Retain data after tool execution completes

### API Token Security
- API tokens are stored only in your local `.env` file
- Tokens are never transmitted except as Bearer tokens in HTTPS requests to DealHub
- The `.env` file is excluded from version control via `.gitignore`
- You should use file system permissions to restrict access to `.env` (e.g., `chmod 600 .env`)

### Compliance
This MCP server:
- Does not handle or store personally identifiable information (PII) beyond what's necessary for API authentication
- Does not access or process health data
- Operates entirely within your local environment and your DealHub instance
- Does not require GDPR, CCPA, or HIPAA compliance as it stores no user data

## Security Considerations

### Authentication Security

**API Token Protection**
- Store tokens in `.env` files, never in code
- Add `.env` to `.gitignore` to prevent accidental commits
- Use restrictive file permissions: `chmod 600 .env`
- Never share tokens in chat, screenshots, or documentation

**Token Rotation**
- Regularly regenerate API tokens (recommended: every 90 days)
- Immediately revoke tokens if compromised
- Use separate tokens for different environments (dev, staging, prod)

### Principle of Least Privilege
- Only admin users should generate API tokens
- Tokens inherit the permissions of the user who generated them
- Do not use super-admin tokens if regular admin access is sufficient

### Network Security
- **HTTPS Required**: The MCP server only communicates with DealHub over HTTPS
- **IP Whitelisting**: Consider configuring IP restrictions in DealHub's API settings
- **Firewall**: Ensure your firewall allows outbound HTTPS to your DealHub instance

### Local Execution Security
- The MCP server runs locally as a subprocess of Claude Desktop
- No network ports are opened or listening
- Communication with Claude uses stdin/stdout (local IPC only)
- The server cannot be accessed remotely

### Dependency Security
- All npm dependencies are from trusted sources (@modelcontextprotocol, axios, dotenv)
- Run `npm audit` regularly to check for vulnerabilities
- Keep dependencies updated: `npm update`

### Secure Configuration

**Claude Desktop Config**
- Store API tokens in environment variables in `claude_desktop_config.json`
- Restrict access to `~/Library/Application Support/Claude/`
- On shared machines, ensure other users cannot read your Claude config

**Environment Variables**
- Never hardcode credentials in `package.json` or source code
- Use `.env` files for local development
- Use secure environment variable management for production deployments

### Operational Security
- **Logging**: The MCP server logs minimal information to stderr
- **Error Messages**: Error messages do not expose sensitive data
- **Input Validation**: All tool inputs are validated before making API calls

### Incident Response
If you suspect a token has been compromised:
1. Immediately revoke the token in DealHub (Settings → Integrations → Partner API)
2. Generate a new token
3. Update your `.env` file with the new token
4. Restart Claude Desktop
5. Review DealHub API access logs for suspicious activity

## Support

For issues or questions:
- DealHub Documentation: https://developers.dealhub.io
- MCP Documentation: https://modelcontextprotocol.io

## License

MIT License - See [LICENSE](LICENSE) file for details.

Copyright (c) 2026 DealHub

This software is provided "as is", without warranty of any kind. See the LICENSE file for full terms.