Templafy MCP Server

A production-ready MCP (Model Context Protocol) server for Templafy Data Sources API. This server provides a middle layer between Claude and the Templafy Public API, focusing exclusively on Data Sources functionality.

Features

• Complete Data Sources API Coverage: All CRUD operations for data sources, fields, items, and item fields
• Type Safety: Full TypeScript support with Zod validation
• Robust Error Handling: Proper HTTP error mapping with special handling for 423 Locked responses
• Retry Logic: Exponential backoff for server errors with configurable retry attempts
• Security: API key redaction in logs, input validation, and rate limiting
• Observability: Structured logging with request tracking and performance metrics
• Production Ready: Comprehensive error handling, graceful shutdown, and proper resource management

Prerequisites

• Node.js 20 or higher
• Templafy API access with Admin permissions
• Valid API key from Templafy Admin

Installation

1. Clone or download this repository
2. Install dependencies:

npm install

3. Copy the environment configuration:

cp env.example .env

4. Configure your environment variables in .env:

# Required
TENANT_ID=your-tenant-id
TEMPLAFY_API_KEY=your-api-key

# Optional (defaults shown)
TEMPLAFY_API_VERSION=v2
AUTH_HEADER_NAME=Authorization
AUTH_SCHEME=ApiKey
REQUEST_TIMEOUT_MS=30000
DEBUG_HTTP=false

Environment Variables

Variable	Required	Default	Description
TENANT_ID	Yes	-	Your Templafy tenant ID
TEMPLAFY_API_KEY	Yes	-	API key from Templafy Admin
TEMPLAFY_API_VERSION	No	v2	API version to use
AUTH_HEADER_NAME	No	Authorization	HTTP header name for authentication
AUTH_SCHEME	No	ApiKey	Authentication scheme
REQUEST_TIMEOUT_MS	No	30000	Request timeout in milliseconds
DEBUG_HTTP	No	false	Enable HTTP request/response logging

Usage

Development

Start the server in development mode with hot reload:

npm run dev

Production

Build and run the production server:

npm run build
node dist/server.js

Registering with Claude Desktop

Add the following configuration to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "templafy": {
      "command": "node",
      "args": ["/path/to/templafy-mcp-server/dist/server.js"],
      "env": {
        "TENANT_ID": "your-tenant-id",
        "TEMPLAFY_API_KEY": "your-api-key"
      }
    }
  }
}

Available Tools

Data Sources

listDataSources

List data sources with optional search and pagination.

Parameters:

• searchQuery (optional): Search query to filter data sources
• page (optional): Page number (default: 1)
• pageSize (optional): Items per page (default: 50, max: 200)

Example:

{
  "searchQuery": "customer data",
  "page": 1,
  "pageSize": 25
}

getDataSource

Get a specific data source by ID.

Parameters:

• id (required): Data source ID

createDataSource

Create a new data source.

Parameters:

• name (required): Data source name
• description (optional): Data source description
• fields (optional): Array of field definitions

Example:

{
  "name": "Customer Database",
  "description": "Customer information and contact details",
  "fields": [
    {
      "name": "Customer Name",
      "type": "text",
      "required": true,
      "description": "Full customer name"
    },
    {
      "name": "Email",
      "type": "text",
      "required": true,
      "description": "Customer email address"
    }
  ]
}

updateDataSource

Update an existing data source.

Parameters:

• id (required): Data source ID
• name (optional): Updated name
• description (optional): Updated description
• fields (optional): Updated field definitions

deleteDataSource

Delete a data source.

Parameters:

• id (required): Data source ID

Fields

getField

Get a specific field from a data source.

Parameters:

• dataSourceId (required): Data source ID
• fieldId (required): Field ID

createField

Create a new field in a data source.

Parameters:

• dataSourceId (required): Data source ID
• field (required): Field definition

Example:

{
  "dataSourceId": "ds-123",
  "field": {
    "name": "Phone Number",
    "type": "text",
    "required": false,
    "description": "Customer phone number"
  }
}

updateField

Update an existing field.

Parameters:

• dataSourceId (required): Data source ID
• fieldId (required): Field ID
• field (required): Updated field definition

deleteField

Delete a field from a data source.

Parameters:

• dataSourceId (required): Data source ID
• fieldId (required): Field ID

Items

listItems

List items in a data source with pagination.

Parameters:

• dataSourceId (required): Data source ID
• page (optional): Page number (default: 1)
• pageSize (optional): Items per page (default: 50, max: 200)

getItem

Get a specific item from a data source.

Parameters:

• dataSourceId (required): Data source ID
• itemId (required): Item ID

createItem

Create a new item in a data source.

Parameters:

• dataSourceId (required): Data source ID
• fields (optional): Item field values

Example:

{
  "dataSourceId": "ds-123",
  "fields": {
    "customer-name": "John Doe",
    "email": "john@example.com",
    "phone": "+1-555-0123"
  }
}

updateItem

Update an existing item.

Parameters:

• dataSourceId (required): Data source ID
• itemId (required): Item ID
• fields (optional): Updated field values

deleteItem

Delete an item from a data source.

Parameters:

• dataSourceId (required): Data source ID
• itemId (required): Item ID

Item Fields

putItemField

Set or update a specific field value for an item.

Parameters:

• dataSourceId (required): Data source ID
• itemId (required): Item ID
• fieldId (required): Field ID
• value (required): Field value (type depends on field type)

Example:

{
  "dataSourceId": "ds-123",
  "itemId": "item-456",
  "fieldId": "field-789",
  "value": "Updated value"
}

deleteItemField

Delete a specific field value from an item.

Parameters:

• dataSourceId (required): Data source ID
• itemId (required): Item ID
• fieldId (required): Field ID

Field Types

The following field types are supported:

• text: Text strings
• number: Numeric values
• image: Image references
• reference: References to other data
• color: Color values
• theme: Theme references
• font: Font specifications

Error Handling

The server provides comprehensive error handling:

• Validation Errors: Input validation with clear error messages
• HTTP Errors: Proper mapping of HTTP status codes to MCP errors
• 423 Locked: Special handling for locked resources with lock reason and dependent resources
• Retry Logic: Automatic retry with exponential backoff for server errors
• Rate Limiting: Built-in protection against excessive API calls

Example Error Response

{
  "ok": false,
  "error": {
    "status": 423,
    "code": "LOCKED",
    "message": "Data source is locked",
    "lockReason": {
      "reason": "Data source is being used by active templates",
      "dependentResources": ["template-1", "template-2"]
    }
  }
}

Development

Scripts

• npm run dev: Start development server with hot reload
• npm run build: Build production bundle
• npm run lint: Run ESLint
• npm run typecheck: Run TypeScript type checking
• npm run test: Run test suite
• npm run test:watch: Run tests in watch mode

Testing

The project includes a comprehensive test suite using Vitest and MSW (Mock Service Worker):

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run specific test file
npm test dataSources.test.ts

Code Structure

src/
├── server.ts              # MCP server entry point
├── templafyClient.ts      # HTTP client with retry logic
├── types.ts              # TypeScript types and Zod schemas
├── tools/                # MCP tool implementations
│   ├── dataSources.ts    # Data source tools
│   ├── fields.ts         # Field tools
│   ├── items.ts          # Item tools
│   └── itemFields.ts     # Item field tools
└── util/                 # Utility modules
    ├── env.ts           # Environment configuration
    ├── logger.ts        # Logging utilities
    └── errors.ts        # Error handling

Security

• API keys are automatically redacted from logs
• Input validation prevents injection attacks
• Rate limiting protects against abuse
• No sensitive data is logged in production

Monitoring

The server provides structured logging with:

• Request/response tracking with unique IDs
• Performance metrics (duration, status codes)
• Error tracking with context
• Optional HTTP debugging mode

Troubleshooting

Common Issues

1. Authentication Errors: Verify your TENANT_ID and TEMPLAFY_API_KEY are correct
2. Timeout Errors: Increase REQUEST_TIMEOUT_MS for slow networks
3. Rate Limiting: The server includes built-in rate limiting; reduce concurrent requests if needed
4. 423 Locked Errors: Check the lockReason for dependent resources that need to be unlocked first

Debug Mode

Enable debug logging to troubleshoot issues:

DEBUG_HTTP=true npm run dev

This will log all HTTP requests and responses (with sensitive data redacted).

License

This project is licensed under the MIT License.