Gthulhu MCP Server

Gthulhu MCP Server is a Model Context Protocol (MCP) server and CLI that turns natural-language scheduling intents into concrete scheduling strategies for the Gthulhu scheduler API. It parses pod labels and human-readable time slices, validates and builds a scheduling strategy payload, and sends it to Gthulhu's REST API.

• Language: TypeScript (Node.js >= 18)
• Scope: MCP server + CLI + typed SDK-like helpers
• Key features:
  • Natural language label parsing and validation
  • Human-readable time conversions (e.g., 10ms → 10000us)
  • Robust config system (env/file), schema validation, and sanitization
  • HTTP client with retries, timeouts, and circuit breaker
  • Structured logging and centralized error handling

Quick start

Prerequisites:

• Node.js 18+
• Access to a running Gthulhu API (or a mock) and an API token

Install dependencies and build:

npm install
npm run build

Run the CLI (from local repo):

# Show help
node dist/cli.js --help

# Start the MCP server (stdio)
node dist/cli.js server

# Or run a tool directly via CLI
node dist/cli.js tool:update \
  --name "priority-frontend" \
  --labels "app=frontend,env=prod" \
  --strategy priority \
  --time-slice "5ms"

If installed globally or via a package manager, the binary name is gthulhu-mcp:

gthulhu-mcp --help
gthulhu-mcp server

Installation

From source:

# Clone, install, build
npm install
npm run build

# Optional: run tests
npm test

From a local build as a CLI (no publish):

# Use the built CLI directly
node dist/cli.js --help

# Or link globally (developer convenience)
npm link
gthulhu-mcp --help

Note: npm start runs node dist/index.js. That entrypoint exports library APIs. For the CLI, use node dist/cli.js or the gthulhu-mcp binary.

Configuration

The server and CLI can be configured via environment variables or a JSON config file. Environment variables take precedence when both are provided.

Common environment variables:

• GTHULHU_API_URL: Base URL of the Gthulhu API (e.g., http://localhost:8080)
• GTHULHU_AUTH_TOKEN (or GTHULHU_API_TOKEN): API token for authentication
• GTHULHU_MCP_PUBLIC_KEY (or GTHULHU_PUBLIC_KEY): Path to PEM public key for JWT token retrieval
• GTHULHU_MCP_HOST: MCP server host (for clients that need a host binding)
• GTHULHU_MCP_PORT: MCP server port (0 to choose a random free port when applicable)
• LOG_LEVEL or GTHULHU_LOG_LEVEL: Logging level (debug, info, warn, error)

You can also use a JSON config file and pass it to the CLI with --config path/to/config.json.

Show current config via CLI:

# Show full config (sanitized by default)
node dist/cli.js config:show

# Show raw config (includes sensitive values) — use with caution
node dist/cli.js config:show --sanitized=false

# Save current config to a file
node dist/cli.js config:save --output ./gthulhu-mcp.config.json

CLI usage

The CLI helps you inspect config, check API health, run tools, and start the MCP server.

# Display help
node dist/cli.js --help

Examples:

# Health check against the API (optionally override URL/token/timeout per call)
node dist/cli.js api:health --url $GTHULHU_API_URL --token $GTHULHU_AUTH_TOKEN --timeout 5000

# Update a scheduling strategy using natural language inputs
node dist/cli.js tool:update \
  --name "priority-frontend" \
  --labels "app=frontend,env=prod" \
  --strategy priority \
  --time-slice "5ms"

# Start the MCP server (for integration with an MCP client)
# Option 1: direct token
node dist/cli.js server --api-url $GTHULHU_API_URL --token $GTHULHU_AUTH_TOKEN

# Option 2: JWT public key flow (server obtains token)
node dist/cli.js server --api-url $GTHULHU_API_URL --public-key /path/to/public.pem

Use --config path to point to a specific config file. Most commands accept overrides (e.g., --url, --token, --timeout).

MCP server

This project implements an MCP server exposing at least the update_scheduling_strategy tool. Typical workflow for an MCP client:

1. Configure your MCP client (e.g., Claude Desktop or another MCP-compatible client) to run the command:
   • Command: gthulhu-mcp server (if installed) or node dist/cli.js server (from source)
2. The client will call list_tools and then call_tool with update_scheduling_strategy and arguments like labels and time slice.
3. The server parses labels, converts human time to microseconds, builds a valid strategy, calls the Gthulhu API, and returns a concise text summary.

Notes:

• Time units are normalized to microseconds (us) in summaries and payloads.
• Unknown labels or invalid time values will be rejected with structured errors.

Library usage

You can also consume this package programmatically:

import {
  createMCPServer,
  ConfigService,
  StrategyBuilderService,
  GthulhuApiClient,
} from 'gthulhu-mcp-server';

// Load config
const config = ConfigService.getInstance().getConfig();

// Build a strategy from inputs
const builder = new StrategyBuilderService();
const payload = builder.build({
  name: 'priority-frontend',
  labels: 'app=frontend,env=prod',
  strategy: 'priority',
  timeSlice: '5ms',
});

// Send to API
const client = new GthulhuApiClient({ baseUrl: config.gthulhuApi.baseUrl, token: config.auth.apiToken });
await client.createStrategies(payload);

// Start MCP server (stdio) if needed
const server = createMCPServer({ apiUrl: config.gthulhuApi.baseUrl, authToken: config.auth.apiToken });
await server.start();

Development

• Build: npm run build
• Lint: npm run lint (fix: npm run lint:fix)
• Format: npm run format
• Test: npm test (watch: npm run test:watch, coverage: npm run test:coverage)
• Clean: npm run clean

Project highlights:

• Strict TypeScript config and Zod-based schema validation
• Jest test setup with ESM-aware mocks for MCP SDK
• Winston logging with structured output and file rotation
• Centralized error handling and retry/backoff wrappers

Environment & compatibility

• Node.js 18+
• No network calls are made unless you invoke an API command or start the MCP server with a real API URL and token.
• For the Gthulhu API server itself, refer to the Gthulhu project documentation.

Work with Coding Agent

To integrate with Coding Agent or another MCP client, configure the client to use this MCP server. Below is an example configuration snippet for Coding Agent:

{
	"servers": {
		"gthulhu": {
			"type": "stdio",
			"command": "node",
			"args": [
				"/home/ian/gthulhu-mcp/dist/cli.js",
				"-c",
				"/home/ian/gthulhu-mcp/config/config.json",
				"server"
			]
		}
	},
	"inputs": []
}

Troubleshooting

• "axios.create is not a function" in tests: ensure the proper test mocks are loaded (already configured in this repo).
• Timeouts or ECONNREFUSED: verify GTHULHU_API_URL is reachable and your GTHULHU_AUTH_TOKEN is valid. Increase timeout via config or api:health --timeout.
• Label parse errors: check for invalid key/value format or unsupported characters.
• MCP client cannot connect: confirm you are launching the MCP server via the CLI (server subcommand) and that your client is configured to use stdio.

Security

• Keep your API token secret. Prefer using environment variables or sanitized config printing (config:show without --sanitized=false).
• Avoid committing configuration files with tokens.

License

GPL-2.0. See LICENSE.