MCP-Templafy-datasources

slaarhuis/MCP-Templafy-datasources

3.1

If you are the rightful owner of MCP-Templafy-datasources and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A production-ready MCP server for Templafy Data Sources API, providing a middle layer between Claude and the Templafy Public API.

Tools
5
Resources
0
Prompts
0

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
  1. Copy the environment configuration:
cp env.example .env
  1. 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

VariableRequiredDefaultDescription
TENANT_IDYes-Your Templafy tenant ID
TEMPLAFY_API_KEYYes-API key from Templafy Admin
TEMPLAFY_API_VERSIONNov2API version to use
AUTH_HEADER_NAMENoAuthorizationHTTP header name for authentication
AUTH_SCHEMENoApiKeyAuthentication scheme
REQUEST_TIMEOUT_MSNo30000Request timeout in milliseconds
DEBUG_HTTPNofalseEnable 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.