@mpisaac-syn/coherence-mcp-bundle/README.md

MCP (Model Context Protocol) bundle server for Coherence Gateway - enables LLMs to interact with domain-specific OpenAPI tool bundles

# @mpisaac-syn/coherence-mcp-bundle

Private MCP (Model Context Protocol) bundle server for Coherence Gateway - enables LLMs like Claude to interact with domain-specific OpenAPI tool bundles through a secure, enterprise-ready interface.

## Overview

This package provides a bundle-aware MCP server that communicates with the Coherence Gateway, exposing only domain-specific tools based on the configured bundle. This reduces cognitive load on LLMs and improves tool selection accuracy.

## Architecture

```
Claude Desktop
     ↓
MCP Bundle Server (this package)
     ↓
Coherence Gateway (your deployment)
     ↓
Docker Runners (petstore-runner, pulsetrack-runner, etc.)
```

## Installation

This is a **private package** hosted on GitHub Package Registry. You need authentication to install it.

### Step 1: GitHub Authentication

First, create a GitHub Personal Access Token:
1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Create a token with `read:packages` scope
3. Save the token securely

### Step 2: Configure NPM

Option A - Global configuration (recommended):
```bash
# Configure npm to use GitHub registry for @mpisaac-syn scope
npm config set @mpisaac-syn:registry https://npm.pkg.github.com

# Login to GitHub registry
npm login --registry=https://npm.pkg.github.com
# Username: your-github-username
# Password: your-personal-access-token
# Email: your-email
```

Option B - Project-specific .npmrc:
```bash
# Create .npmrc in your home directory
echo "@mpisaac-syn:registry=https://npm.pkg.github.com" >> ~/.npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> ~/.npmrc
```

### Step 3: Install or Use

With npx (no installation required):
```bash
npx @mpisaac-syn/coherence-mcp-bundle --bundle finance-ops
```

Or install globally:
```bash
npm install -g @mpisaac-syn/coherence-mcp-bundle
coherence-mcp --bundle finance-ops
```

## Usage with Claude Desktop

### Single Bundle Configuration

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

```json
{
  "mcpServers": {
    "coherence-finance": {
      "command": "npx",
      "args": [
        "@mpisaac-syn/coherence-mcp-bundle",
        "--bundle",
        "finance-ops"
      ],
      "env": {
        "COHERENCE_GATEWAY_URL": "http://localhost:8000",
        "COHERENCE_JWT_SECRET": "your-jwt-secret"
      }
    }
  }
}
```

### Multiple Bundle Configuration

Configure multiple domain-specific servers:

```json
{
  "mcpServers": {
    "coherence-finance": {
      "command": "npx",
      "args": ["@mpisaac-syn/coherence-mcp-bundle", "--bundle", "finance-ops"],
      "env": {
        "COHERENCE_GATEWAY_URL": "https://coherence.synapsedx.co.uk",
        "COHERENCE_JWT_SECRET": "your-jwt-secret"
      }
    },
    "coherence-hr": {
      "command": "npx",
      "args": ["@mpisaac-syn/coherence-mcp-bundle", "--bundle", "hr-admin"],
      "env": {
        "COHERENCE_GATEWAY_URL": "https://coherence.synapsedx.co.uk",
        "COHERENCE_JWT_SECRET": "your-jwt-secret"
      }
    },
    "coherence-sales": {
      "command": "npx",
      "args": ["@mpisaac-syn/coherence-mcp-bundle", "--bundle", "sales-mgmt"],
      "env": {
        "COHERENCE_GATEWAY_URL": "https://coherence.synapsedx.co.uk",
        "COHERENCE_JWT_SECRET": "your-jwt-secret"
      }
    }
  }
}
```

## Configuration Options

| Option | Environment Variable | Default | Description |
|--------|---------------------|---------|-------------|
| `--gateway-url` | `COHERENCE_GATEWAY_URL` | `http://localhost:8000` | Coherence Gateway URL |
| `--jwt-secret` | `COHERENCE_JWT_SECRET` | Development default | JWT secret for authentication |
| `--log-level` | `COHERENCE_LOG_LEVEL` | `INFO` | Log level (DEBUG, INFO, WARNING, ERROR) |
| `--bundle` | `COHERENCE_BUNDLE` | None (all tools) | Bundle name for domain-specific filtering |

## Bundle Names

Common bundle names configured in Coherence:
- `finance-ops` - Financial operations tools (invoicing, expenses, budgets)
- `hr-admin` - HR administration tools (employees, timesheets, benefits)
- `sales-mgmt` - Sales management tools (CRM, leads, pipeline)
- `it-ops` - IT operations tools (monitoring, tickets, deployments)
- `marketing` - Marketing tools (campaigns, analytics, content)

Check with your Coherence administrator for available bundles in your deployment.

## Gateway Deployment Flexibility

The MCP bundle server can connect to any Coherence Gateway deployment:

### Local Development
```bash
npx @mpisaac-syn/coherence-mcp-bundle --bundle finance-ops --gateway-url http://localhost:8000
```

### Production Cloud
```bash
npx @mpisaac-syn/coherence-mcp-bundle --bundle finance-ops --gateway-url https://coherence.synapsedx.co.uk
```

### Enterprise Internal
```bash
npx @mpisaac-syn/coherence-mcp-bundle --bundle finance-ops --gateway-url https://coherence.internal.company.com
```

## Development

To run in development mode:

```bash
# Clone the repository
git clone https://github.com/MPIsaac-Syn/coherence.git
cd coherence/mcp_adapter/npm

# Install dependencies
npm install

# Link for local development
npm link

# Test with a bundle
coherence-mcp --bundle finance-ops --log-level DEBUG
```

## Security

- **Private Package**: Only accessible to authorized GitHub users
- **JWT Authentication**: Secure communication with Gateway
- **No Credentials Storage**: API secrets remain in Gateway's Azure Key Vault
- **Bundle Isolation**: Each MCP server instance only sees its bundle's tools
- **Gateway Flexibility**: Connect to any authorized Gateway deployment

## Troubleshooting

### Authentication Issues

```bash
# Verify GitHub authentication
npm whoami --registry=https://npm.pkg.github.com

# Re-authenticate if needed
npm logout --registry=https://npm.pkg.github.com
npm login --registry=https://npm.pkg.github.com
```

### Bundle Not Found

```bash
# List available bundles (requires gateway connection)
npx @mpisaac-syn/coherence-mcp-bundle --list-bundles

# Check specific bundle
npx @mpisaac-syn/coherence-mcp-bundle --bundle finance-ops --log-level DEBUG
```

### Gateway Connection Issues

```bash
# Test gateway health
curl http://localhost:8000/health

# Test with explicit configuration
COHERENCE_GATEWAY_URL=http://localhost:8000 \
COHERENCE_LOG_LEVEL=DEBUG \
npx @mpisaac-syn/coherence-mcp-bundle --bundle finance-ops
```

## Support

- **Internal Issues**: Contact your Coherence administrator
- **Package Issues**: https://github.com/MPIsaac-Syn/coherence/issues
- **Documentation**: https://github.com/MPIsaac-Syn/coherence

## License

UNLICENSED - Proprietary to SynapseDx

© 2025 SynapseDx. All rights reserved.