npm package: @haneeshpld/csp-entitlements-mcp
Description: MCP server for CSP entitlements lookup - Watson Orchestrate compatible
Author: haneesh
Latest version: 1.0.2

# CSP Entitlements MCP Server

Model Context Protocol (MCP) server for CSP entitlements lookup. Compatible with Watson Orchestrate and other MCP clients.

## Overview

This MCP server provides tools for querying user entitlements from a CSP (Cloud Service Provider) system. It supports both stdio and SSE transports, making it suitable for local CLI integrations and remote HTTP access.

## Features

- **Two MCP Tools**:
  - `csp_entitlement_lookup`: Query user entitlements by userId or email
  - `healthcheck`: Get server health and version information

- **Dual Transport Support**:
  - `stdio`: For local/CLI integrations (default)
  - `sse`: HTTP Server-Sent Events for remote access

- **Mock Provider**: In-memory dataset for testing and development
- **Extensible**: Provider interface allows easy integration with real CSP APIs

## Installation

### Via npx (Recommended for Watson Orchestrate)

```bash
# From npm registry
npx -y @haneesh/csp-entitlements-mcp@1.0.0 --transport stdio

# From tarball URL
npx -y https://your-artifact-server.com/csp-entitlements-mcp-1.0.0.tgz --transport stdio
```

### Local Development

```bash
# Clone and install
git clone <repository-url>
cd csp-entitlements-mcp
npm install

# Build
npm run build

# Run locally
npm start
```

## Usage

### Command Line Options

```bash
csp-entitlements-mcp [options]

Options:
  --transport <type>  Transport type: stdio or sse (default: "stdio")
  --port <number>     Port for SSE transport (default: "8080")
  --host <string>     Host for SSE transport (default: "127.0.0.1")
  --data <path>       Path to custom JSON dataset file
  -V, --version       Output the version number
  -h, --help          Display help
```

### Environment Variables

- `LOG_LEVEL`: Set logging level (debug, info, warn, error)
- `CSP_PROVIDER`: Provider type (currently only "mock" is implemented)

### Examples

#### Stdio Transport (Default)

```bash
# Using npx
npx -y @haneesh/csp-entitlements-mcp

# With custom data file
npx -y @haneesh/csp-entitlements-mcp --data ./my-data.json

# With debug logging
LOG_LEVEL=debug npx -y @haneesh/csp-entitlements-mcp
```

#### SSE Transport (HTTP Server)

```bash
# Start HTTP server on default port 8080
npx -y @haneesh/csp-entitlements-mcp --transport sse

# Custom host and port
npx -y @haneesh/csp-entitlements-mcp --transport sse --host 0.0.0.0 --port 3000
```

## MCP Tools

### csp_entitlement_lookup

Lookup CSP entitlements for a user.

**Input Schema:**
```json
{
  "userId": "string (optional)",
  "email": "string (optional)",
  "token": "string (optional, for future use)"
}
```

Note: At least one of `userId` or `email` must be provided.

**Output:**
```json
{
  "entitlements": [
    {
      "entitlementId": "ent-001",
      "productId": "prod-photoshop",
      "productName": "Adobe Photoshop",
      "level": "Full Support",
      "status": "Active",
      "startDate": "2024-01-01T00:00:00Z",
      "endDate": "2025-12-31T23:59:59Z"
    }
  ],
  "coverage": {
    "is_partial": false,
    "notes": "Optional notes about the lookup"
  },
  "request_id": "uuid-v4"
}
```

**Example Client Call:**
```javascript
// Using MCP SDK
const result = await client.callTool('csp_entitlement_lookup', {
  email: 'john.doe@company.com'
});
```

### healthcheck

Check server health and get version information.

**Input Schema:**
```json
{}
```

**Output:**
```json
{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2024-03-06T10:30:00.000Z"
}
```

## Watson Orchestrate Integration

### Installation Command

Paste this into Watson Orchestrate's "Install MCP Server" field:

**From npm registry:**
```bash
npx -y @haneesh/csp-entitlements-mcp@1.0.0 --transport stdio
```

**From internal artifact server:**
```bash
npx -y https://your-internal-server.com/artifacts/csp-entitlements-mcp-1.0.0.tgz --transport stdio
```

### Using in Watson Orchestrate

Once installed, you can use natural language to invoke the tools:

```
"Show me the entitlements for user john.doe@company.com"

"Check the health of the CSP entitlements server"

"What products does user-001 have access to?"
```

## Data Format

The server uses a JSON dataset with the following structure:

```json
{
  "users": [
    {
      "userId": "user-001",
      "email": "john.doe@company.com",
      "entitlements": [
        {
          "entitlementId": "ent-001",
          "productId": "prod-photoshop",
          "productName": "Adobe Photoshop",
          "level": "Full Support",
          "status": "Active",
          "startDate": "2024-01-01T00:00:00Z",
          "endDate": "2025-12-31T23:59:59Z"
        }
      ]
    }
  ]
}
```

You can provide a custom dataset using the `--data` flag.

## Development

### Build

```bash
npm run build
```

### Test

```bash
npm test
```

### Lint

```bash
npm run lint
```

### Package

```bash
# Create tarball
npm pack

# This creates: haneesh-csp-entitlements-mcp-1.0.0.tgz
```

## Troubleshooting

### Common Issues

#### "Cannot find module" errors

**Problem**: Missing dependencies after npx install.

**Solution**: 
```bash
# Clear npx cache
npx clear-npx-cache

# Try again
npx -y @haneesh/csp-entitlements-mcp
```

#### Permission denied

**Problem**: Cannot execute the CLI.

**Solution**:
```bash
# If running from local build
chmod +x dist/cli.js

# Or use node directly
node dist/cli.js
```

#### Node version mismatch

**Problem**: Server requires Node.js 18+.

**Solution**:
```bash
# Check version
node --version

# Upgrade if needed (using nvm)
nvm install 18
nvm use 18
```

#### Server not responding

**Problem**: Server starts but doesn't respond to requests.

**Solution**:
1. Check logs (stderr output)
2. Verify transport mode matches client expectations
3. For SSE mode, ensure port is not in use:
   ```bash
   lsof -i :8080
   ```

#### Empty entitlements returned

**Problem**: Lookup succeeds but returns no entitlements.

**Solution**:
1. Verify user exists in dataset
2. Check entitlement dates (must be active)
3. Ensure entitlement status is "Active"
4. Try with `--data` flag to use custom dataset

### Debug Mode

Enable debug logging to see detailed information:

```bash
LOG_LEVEL=debug npx -y @haneesh/csp-entitlements-mcp
```

### Testing Locally

```bash
# Build and run
npm run build
npm start

# In another terminal, test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/cli.js
```

## Architecture

```
src/
├── cli.ts                          # CLI entry point
├── server.ts                       # MCP server implementation
├── tools/
│   ├── entitlement.ts             # Entitlement lookup tool
│   └── health.ts                  # Health check tool
├── providers/
│   ├── entitlementProvider.ts     # Provider interface
│   └── mockEntitlementProvider.ts # Mock implementation
└── data/
    └── entitlements.sample.json   # Sample dataset
```

## Extending

### Adding a Real CSP Provider

1. Implement the `EntitlementProvider` interface:

```typescript
import { EntitlementProvider, EntitlementLookupRequest, EntitlementLookupResponse } from './entitlementProvider';

export class RealCSPProvider implements EntitlementProvider {
  async lookup(request: EntitlementLookupRequest): Promise<EntitlementLookupResponse> {
    // Call real CSP API
    const response = await fetch(`https://csp-api.com/entitlements?userId=${request.userId}`);
    // Transform and return
  }
}
```

2. Update `server.ts` to use the new provider:

```typescript
// In constructor
if (process.env.CSP_PROVIDER === 'real') {
  this.provider = new RealCSPProvider();
} else {
  this.provider = new MockEntitlementProvider(config.dataPath);
}
```

### Adding New Tools

1. Create tool definition in `src/tools/`
2. Register in `server.ts` `setupHandlers()`
3. Add handler in `CallToolRequestSchema` switch statement

## License

Apache-2.0

## Support

For issues and questions, please contact the development team or open an issue in the repository.