@gotillit/local-mcp-server

Exposes the complete Tillit API surface as a structured tool registry conforming to the Model Context Protocol specification. Each tool is defined with JSON schemas for input validation, output typing, and error handling. The server implements the MCP tool discovery protocol, allowing clients like Claude Desktop to enumerate, inspect, and invoke tools with full type safety and documentation inheritance from the underlying Tillit API.

Implements MCP's resource protocol to expose Tillit domain entities (orders, inventory, work centers, BOMs, etc.) as queryable resources with URI-based addressing. Resources are indexed and cached locally, enabling Claude to retrieve entity details, relationships, and metadata without repeated API calls. The server maintains a resource manifest describing available entity types, their schemas, and navigation patterns for semantic understanding.

Exposes HTTP health check endpoints (/health, /ready) that report server status, Tillit API connectivity, and resource availability. Health checks verify that the MCP server is running, can authenticate with Tillit, and has sufficient resources (memory, disk). Readiness probes indicate whether the server is ready to accept tool invocations (vs. still initializing). Health check results are cached briefly to avoid excessive Tillit API calls. The server reports detailed health status including component-level diagnostics (auth status, API latency, resource usage).

Parses Tillit API specifications (OpenAPI/Swagger or introspection endpoints) to automatically generate JSON schemas for all 195+ tools and 48+ resources. Embeds documentation strings, parameter descriptions, and usage examples directly into tool/resource definitions. The server maintains schema versioning and validates incoming requests against schemas before forwarding to Tillit, providing early error detection and clear validation feedback to Claude.

Runs as a standalone Node.js process implementing the MCP server protocol, compatible with Claude Desktop's native MCP client. The server listens on stdio or HTTP transport, handles MCP protocol handshakes, and manages bidirectional communication with Claude. Configuration is stored in Claude Desktop's MCP config file, enabling one-click activation without custom client code. The server manages its own lifecycle, including graceful shutdown and error recovery.

Implements exponential backoff retry logic for transient Tillit API failures (5xx errors, timeouts), with configurable retry counts and backoff multipliers. Translates Tillit API errors into structured MCP error responses with HTTP status codes, error codes, and human-readable messages. The server distinguishes between retryable errors (network timeouts, 503 Service Unavailable) and permanent failures (401 Unauthorized, 404 Not Found), preventing infinite retry loops on authentication or validation errors.

Abstracts Tillit API authentication (API key, OAuth 2.0, or custom tokens) into a pluggable credential provider. Credentials are loaded from environment variables, config files, or secure credential stores at server startup. The server handles token refresh for OAuth flows, credential expiration detection, and automatic re-authentication without interrupting active tool invocations. Credentials are never logged or exposed in error messages, maintaining security posture.

Enables Claude to invoke multiple Tillit tools in sequence, with the MCP server tracking data dependencies between tool outputs and subsequent inputs. The server maintains execution context across tool calls, allowing Claude to reference previous results (e.g., 'use the order ID from the previous query'). Implements basic dependency validation to detect circular references or missing prerequisites before execution, reducing wasted API calls.

Implements client-side rate limiting to respect Tillit API quotas (requests per minute, concurrent connections, etc.). The server tracks API call counts per operation type and enforces backpressure by queuing excess requests or returning 429 Too Many Requests errors. Rate limit state is maintained in memory with optional persistence to Redis or similar for multi-instance deployments. The server exposes rate limit status to Claude, enabling intelligent request batching and retry scheduling.

Implements structured logging (JSON format) for all MCP protocol events, tool invocations, API calls, and errors. Logs include timestamps, request/response metadata, execution duration, and error details. The server supports multiple log sinks (stdout, files, external services like DataDog or Splunk) with configurable verbosity levels. Sensitive data (credentials, personal information) is automatically redacted from logs. Execution traces can be correlated across multiple tool invocations using request IDs.

Loads server configuration from a combination of config files (JSON/YAML), environment variables, and command-line arguments, with a clear precedence order (CLI > env vars > config file > defaults). Configuration includes Tillit API endpoint, authentication method, rate limits, logging level, and MCP transport settings. The server validates configuration at startup and provides clear error messages for missing or invalid settings. Configuration can be reloaded without restarting the server (for non-critical settings).