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)

# From npm registry
npx -y @haneesh/[email protected] --transport stdio

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

Local Development

# 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

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)

# 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)

# 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:

{
  "userId": "string (optional)",
  "email": "string (optional)",
  "token": "string (optional, for future use)"
}

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

Output:

{
  "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:

// Using MCP SDK
const result = await client.callTool('csp_entitlement_lookup', {
  email: '[email protected]'
});

healthcheck

Check server health and get version information.

Input Schema:

{}

Output:

{
  "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:

npx -y @haneesh/[email protected] --transport stdio

From internal artifact server:

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 [email protected]"

"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:

{
  "users": [
    {
      "userId": "user-001",
      "email": "[email protected]",
      "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

npm run build

Test

npm test

Lint

npm run lint

Package

# 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:

# Clear npx cache
npx clear-npx-cache

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

Permission denied

Problem: Cannot execute the CLI.

Solution:

# 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:

# 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:

   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:

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

Testing Locally

# 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:

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:

// 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.