Local Mcp Server

# Tillit Local MCP Server A local Model Context Protocol (MCP) server for the Tillit API, built with [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk). This server provides 195+ tools and 48+ resources for complete access to the Tillit manufacturing operations platform. ## Quick Start ### Using npx (Recommended) ```bash TENANT=your-tenant ENV_NAME=development API_KEY=your-key SECRET=your-secret npx @gotillit/local-mcp-server ``` ### Using .env file (Recommended for Development) Copy the example file and customize it: ```bash cp .env.example .env ``` Then edit `.env` with your actual values: ```bash TENANT=bottling ENV_NAME=development API_KEY=your-oauth2-client-id SECRET=your-oauth2-client-secret ``` Then run: ```bash npx @gotillit/local-mcp-server ``` ### Manual Installation ```bash npm install -g @gotillit/local-mcp-server TENANT=your-tenant ENV_NAME=development API_KEY=your-key SECRET=your-secret tillit-mcp-server ``` ## Environment Variables ### Required - `TENANT` - Your tenant name (e.g., "bottling", "manufacturing") - `ENV_NAME` - Environment name (e.g., "development", "staging", "production") - `API_KEY` - OAuth2 client ID for token authentication - `SECRET` - OAuth2 client secret for token authentication ### URL Construction The server automatically constructs URLs using the format: **API Gateway URL:** - Development: `https://{TENANT}.development.tillit-dev.cloud/api` - Other environments: `https://{TENANT}.tillit-{ENV_NAME}.cloud/api` **OAuth2 Token URL:** - Development: `https://{TENANT}.development.tillit-dev.cloud/oauth2/token` - Other environments: `https://{TENANT}.tillit-{ENV_NAME}.cloud/oauth2/token` Examples: - `TENANT=bottling` + `ENV_NAME=development` → - API: `https://bottling.development.tillit-dev.cloud/api` - Auth: `https://bottling.development.tillit-dev.cloud/oauth2/token` ## Claude Desktop Integration Add this configuration to your Claude Desktop settings: ```json { "mcpServers": { "tillit": { "command": "npx", "args": ["@gotillit/local-mcp-server"], "env": { "TENANT": "bottling", "ENV_NAME": "development", "API_KEY": "your-api-key", "SECRET": "your-secret", "REGION": "ap-southeast" } } } } ``` Alternatively, if you have a `.env` file in the package directory, you can use a simpler configuration: ```json { "mcpServers": { "tillit": { "command": "npx", "args": ["@gotillit/local-mcp-server"] } } } ``` ## Features ### 195+ API Tools The server automatically provides tools for all Tillit API operations: - **Search**: 4 tools for finding assets, orders, materials, and activities - **Asset Management**: 12 tools for creating, updating, and managing assets - **Material Management**: 41 tools for materials, groups, tolerances, movements, and conversions - **Order Management**: 49 tools for orders, instances, templates, components, and attributes - **Activity Management**: 89 tools for templates, instances, assignments, reporting, and image handling ### 48+ Resources Access structured information about different API categories: - `tillit://Search` - Search operations - `tillit://Assets` - Asset management - `tillit://Materials` - Material operations - `tillit://Orders` - Order management - `tillit://Activities` - Activity workflows - And 43+ more categories... ### 📚 Built-in Documentation The server includes comprehensive documentation resources accessible through MCP: - `tillit://documentation/overview` - Complete usage guide with common patterns - `tillit://documentation/search` - Search tools documentation - `tillit://documentation/assets` - Asset management tools - `tillit://documentation/materials` - Material handling tools - `tillit://documentation/orders` - Production order tools - `tillit://documentation/activities` - Workflow management tools Each documentation resource provides: - Usage guidance and best practices - Complete tool inventory with descriptions - Detailed parameter specifications - Schema information for request bodies - Common workflow patterns ## Authentication The server uses **OAuth2 Client Credentials Grant** for authentication: ### OAuth2 Authentication The server automatically manages OAuth2 tokens using your client credentials: ```bash TENANT=bottling ENV_NAME=development API_KEY=your-client-id SECRET=your-client-secret npx @gotillit/local-mcp-server ``` The authentication flow: 1. Requests access token from Cognito using client credentials 2. Automatically refreshes tokens when they expire 3. Handles 401 responses by refreshing tokens 4. Uses Bearer token authentication for all API calls ### Tenant Context The `TENANT` environment variable is automatically added as a header: ``` tillit-tenant: bottling ``` ## Example Usage Once connected to an MCP client (like Claude Desktop), you can: ### Access Documentation ``` Read the "tillit://documentation/overview" resource to get started with usage patterns ``` ### List Available Tools The client will automatically discover all 195+ available tools organized by category. ### Execute API Operations ``` Use the "getAllAssets" tool to get all assets Use the "getActiveActivities" tool to see available work Use the "search" tool to find assets containing "motor" in their name ``` ### Work with Activities ``` Use "getActiveActivities" to see available work Use "claimActivity" to assign work to yourself Use "submitActivity" when work is complete ``` ### Access Resources by Category ``` Read the "tillit://Activities" resource to see all activity-related operations Read the "tillit://Materials" resource to see all material management tools ``` ## Troubleshooting ### Server Won't Start - Verify all required environment variables are set: `TENANT`, `ENV_NAME`, `API_KEY`, `SECRET` - Check Node.js version (requires Node 18+) - Ensure network connectivity to your Tillit API - Verify the constructed URLs are accessible ### Authentication Errors - Verify `API_KEY` (client ID) and `SECRET` (client secret) are correct OAuth2 credentials - Check that your OAuth2 client has the required permissions - Ensure the tenant name matches your account setup - Verify the constructed OAuth2 token URL is accessible ### Tool Execution Failures - Check that your OAuth2 client has the required permissions for the specific operations - Verify the target API endpoint is accessible - Review the tool parameters match the API requirements - Check the server logs for detailed error messages ### Environment Variable Issues - Environment variables from the shell take precedence over `.env` file values - The `.env` file is only loaded if required variables are missing from the environment - Check for typos in variable names (case-sensitive) - Ensure the `.env` file is in the correct location if using file-based configuration ## Development ### Local Development Setup ```bash git clone <repository-url> cd tillit-sdk/clients/tillit-mcp/local npm install npm run build node src/index.js ``` ### Building from Source The build process copies the latest MCP tools and resources: ```bash npm run build ``` ### Running Tests ```bash npm run test:all # Run all tests npm run test:oauth2 # Test OAuth2 authentication npm run test:docs # Test documentation loading ``` ## Technical Details - **Runtime**: Node.js 18+ - **Protocol**: MCP over stdio transport - **Authentication**: OAuth2 Client Credentials Grant with automatic token management - **Dependencies**: @modelcontextprotocol/sdk, axios, dotenv - **Architecture**: ES modules with comprehensive error handling and logging ## API Coverage The server provides access to these Tillit API areas: - `/core/search` - Universal search capabilities - `/core/assets/*` - Asset management operations - `/core/materials/*` - Material handling and inventory - `/core/material-*` - Material groups, tolerances, conversions - `/core/orders/*` - Order management and tracking - `/core/order-*` - Order instances, templates, components - `/activity/*` - Complete activity workflow management ## Support For issues, questions, or feature requests, please contact the Tillit team or refer to the main project documentation. ## License Apache-2.0