npm package: @gotillit/local-mcp-server
Description: Local MCP server for Tillit API using @modelcontextprotocol/sdk. Provides 195+ tools and 48+ resources for complete Tillit API access with built-in documentation.
Author: Rafael Amaral
Latest version: 0.0.18

# 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