@layer7/n8n-tanss-api

Modular, reusable MCP-compatible TANSS API tool for n8n AI Agent with comprehensive German UI support.

Overview

This tool provides a complete integration of the TANSS API for n8n AI Agents, enabling professional automation and intelligent ticket management. Built with MCP (Model Context Protocol) compatibility, it offers dynamic command discovery, comprehensive error handling, and seamless AI agent integration.

Features

🤖 AI Agent Integration

• MCP-compatible: Full Model Context Protocol support for AI agents
• Dynamic command discovery: Automatic endpoint detection from OpenAPI specification
• Context-aware suggestions: AI agents can suggest relevant actions based on current context
• Introspectable schemas: Machine-readable command and parameter schemas
• Agent-friendly naming: Commands follow tanss.{resource}.{operation} pattern

🔧 Core Capabilities

• Complete API coverage: All TANSS API endpoints supported
• Resource modules: Tickets, companies, employees, devices, contracts, and more
• Authentication: Bearer token and username/password support
• Parameter validation: OpenAPI schema-based validation
• Error handling: Comprehensive 4xx/5xx, network, and parsing error handling
• Optional parameters: Filter, pagination, sorting, field selection

🛠️ Usage Modes

• CLI mode: Manual debugging and testing
• n8n GUI: Visual configuration in n8n interface
• Direct embedding: Agent-prompt integration
• MCP server: Standalone MCP server for AI agents

Installation

npm install @layer7/n8n-tanss-api

Quick Start

AI Agent Usage

// Direct agent integration
const result = await agent.call('tanss.tickets.list', { 
  status: 'open',
  limit: 10 
});

// Create a new ticket
await agent.call('tanss.tickets.create', {
  title: 'System Issue',
  description: 'Server not responding',
  priority: 'high'
});

// Search companies
const companies = await agent.call('tanss.companies.list', {
  search: 'Acme Corp'
});

CLI Usage

# List available commands
tanss-cli list-commands

# Execute a command
tanss-cli call tanss.tickets.list --params '{"status":"open"}'

# Get command schema
tanss-cli schema tanss.tickets.create

# Test connection
tanss-cli test --url https://your-tanss.com --token your-token

# Interactive mode
tanss-cli interactive

n8n Configuration

1. Add Credentials:

   • Go to n8n Credentials
   • Add "TANSS API" credential
   • Configure:
     • Server URL: https://your-tanss-server.com
     • Authentication: Bearer Token or Username/Password
     • Token/Credentials: Your TANSS API credentials

2. Use in Workflows:

   • Add "TANSS AI Agent" node
   • Select your credential
   • Choose operation (List Tickets, Create Company, etc.)
   • Configure parameters

MCP Server

# Start MCP server
npm run mcp:server

# Or programmatically
import { TanssMCPServer } from '@layer7/n8n-tanss-api';

const server = new TanssMCPServer({
  url: 'https://your-tanss.com',
  token: 'your-token'
});

await server.start();

API Reference

Available Resources

Tickets

• tanss.tickets.list - List tickets with filtering
• tanss.tickets.get - Get ticket by ID
• tanss.tickets.create - Create new ticket
• tanss.tickets.update - Update existing ticket
• tanss.tickets.delete - Delete ticket

Companies

• tanss.companies.list - List companies
• tanss.companies.get - Get company by ID
• tanss.companies.create - Create new company
• tanss.companies.update - Update company
• tanss.companies.delete - Delete company

Employees

• tanss.employees.list - List employees
• tanss.employees.get - Get employee by ID
• tanss.employees.create - Create new employee
• tanss.employees.update - Update employee
• tanss.employees.delete - Delete employee

Devices

• tanss.devices.list - List devices
• tanss.devices.get - Get device by ID
• tanss.devices.create - Create new device
• tanss.devices.update - Update device
• tanss.devices.delete - Delete device

Contracts

• tanss.contracts.list - List contracts
• tanss.contracts.get - Get contract by ID
• tanss.contracts.create - Create new contract
• tanss.contracts.update - Update contract
• tanss.contracts.delete - Delete contract

Command Parameters

All commands support standard parameters:

interface BaseParameters {
  // Pagination
  limit?: number;
  offset?: number;
  
  // Filtering
  filter?: Record<string, any>;
  search?: string;
  
  // Field selection
  fields?: string[];
  
  // Sorting
  sort?: string;
  order?: 'asc' | 'desc';
}

Example Schemas

List Tickets

{
  "name": "tanss.tickets.list",
  "description": "List tickets with optional filtering and pagination",
  "inputSchema": {
    "type": "object",
    "properties": {
      "status": {
        "type": "string",
        "description": "Filter by ticket status",
        "enum": ["open", "closed", "pending"]
      },
      "priority": {
        "type": "string",
        "description": "Filter by priority level",
        "enum": ["low", "medium", "high", "urgent"]
      },
      "limit": {
        "type": "number",
        "description": "Maximum number of results",
        "default": 50
      },
      "offset": {
        "type": "number",
        "description": "Number of results to skip",
        "default": 0
      }
    }
  }
}

Create Ticket

{
  "name": "tanss.tickets.create",
  "description": "Create a new support ticket",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "Ticket title",
        "required": true
      },
      "description": {
        "type": "string",
        "description": "Detailed description of the issue",
        "required": true
      },
      "priority": {
        "type": "string",
        "description": "Priority level",
        "enum": ["low", "medium", "high", "urgent"],
        "default": "medium"
      },
      "companyId": {
        "type": "number",
        "description": "ID of the company this ticket belongs to"
      }
    },
    "required": ["title", "description"]
  }
}

Configuration

Environment Variables

# TANSS Server Configuration
TANSS_URL=https://your-tanss-server.com
TANSS_TOKEN=your-bearer-token

# Alternative: Username/Password
TANSS_USERNAME=your-username
TANSS_PASSWORD=your-password

# Optional: Advanced Configuration
TANSS_TIMEOUT=30000
TANSS_RETRY_ATTEMPTS=3
TANSS_DEBUG=true

Configuration File

Create tanss.config.json:

{
  "url": "https://your-tanss-server.com",
  "auth": {
    "type": "token",
    "token": "your-bearer-token"
  },
  "options": {
    "timeout": 30000,
    "retryAttempts": 3,
    "debug": false
  }
}

AI Agent Examples

Ticket Management Workflow

// AI Agent can automatically handle ticket workflows
async function handleCustomerIssue(customerEmail, issueDescription) {
  // 1. Find customer company
  const companies = await agent.call('tanss.companies.list', {
    search: customerEmail.split('@')[1]
  });
  
  if (companies.length === 0) {
    // 2. Create new company if not found
    const company = await agent.call('tanss.companies.create', {
      name: customerEmail.split('@')[1],
      email: customerEmail
    });
  }
  
  // 3. Create ticket
  const ticket = await agent.call('tanss.tickets.create', {
    title: 'Customer Issue',
    description: issueDescription,
    companyId: companies[0]?.id || company.id,
    priority: 'medium'
  });
  
  return ticket;
}

Automated Reporting

// Generate daily ticket report
async function generateDailyReport() {
  const openTickets = await agent.call('tanss.tickets.list', {
    status: 'open'
  });
  
  const urgentTickets = await agent.call('tanss.tickets.list', {
    status: 'open',
    priority: 'urgent'
  });
  
  return {
    totalOpen: openTickets.length,
    urgent: urgentTickets.length,
    tickets: urgentTickets
  };
}

Context-Aware Suggestions

The AI agent can suggest relevant actions based on context:

// Agent automatically suggests relevant commands
const suggestions = await agent.suggestActions({
  hasOpenTickets: true,
  ticketManagement: true,
  companyManagement: false
});

// Returns: ['tanss.tickets.list', 'tanss.tickets.create']

Error Handling

The tool provides comprehensive error handling:

try {
  const result = await agent.call('tanss.tickets.create', {
    title: 'Test Ticket'
    // Missing required 'description' field
  });
} catch (error) {
  if (error.type === 'validation') {
    console.log('Validation errors:', error.errors);
    // ['Missing required parameter: description']
  } else if (error.type === 'network') {
    console.log('Network error:', error.message);
  } else if (error.type === 'api') {
    console.log('API error:', error.status, error.message);
  }
}

TypeScript Support

Complete TypeScript definitions are included:

import { TanssAPI, TicketCreateParams, TicketListParams } from '@layer7/n8n-tanss-api';

interface TicketCreateParams {
  title: string;
  description: string;
  priority?: 'low' | 'medium' | 'high' | 'urgent';
  companyId?: number;
  assigneeId?: number;
  dueDate?: string;
  tags?: string[];
}

interface TicketListParams extends BaseListParams {
  status?: 'open' | 'closed' | 'pending';
  priority?: 'low' | 'medium' | 'high' | 'urgent';
  assigneeId?: number;
  companyId?: number;
  createdAfter?: string;
  createdBefore?: string;
}

// Usage with full type safety
const api = new TanssAPI({
  url: 'https://your-tanss.com',
  token: 'your-token'
});

const tickets: Ticket[] = await api.tickets.list({
  status: 'open',
  limit: 50
});

Versioning & API Coverage

Endpoint Coverage Matrix

The tool provides 100% coverage of the TANSS API specification:

Resource	List	Get	Create	Update	Delete	Coverage
Tickets	✅	✅	✅	✅	✅	100%
Companies	✅	✅	✅	✅	✅	100%
Employees	✅	✅	✅	✅	✅	100%
Devices	✅	✅	✅	✅	✅	100%
Contracts	✅	✅	✅	✅	✅	100%
Time Entries	✅	✅	✅	✅	✅	100%
Departments	✅	✅	✅	✅	✅	100%

Command Schema Export

All commands are exported in command.schema.json for AI autocompletion:

{
  "tanss.tickets.list": {
    "name": "tanss.tickets.list",
    "description": "List tickets with filtering and pagination",
    "category": "tickets",
    "resource": "tickets",
    "operation": "list",
    "method": "GET",
    "path": "/tickets",
    "inputSchema": { ... },
    "outputSchema": { ... }
  }
}

Development

Building from Source

# Clone repository
git clone https://github.com/julez4125/tanss-n8n-mcp-tool.git
cd tanss-n8n-mcp-tool

# Install dependencies
pnpm install

# Build project
pnpm build

# Run tests
pnpm test

# Start development server
pnpm dev

Adding New Endpoints

The tool automatically discovers new endpoints from the OpenAPI specification:

1. Update the OpenAPI spec file
2. Restart the tool
3. New commands are automatically available

Custom Resource Modules

import { BaseResource } from '@layer7/n8n-tanss-api';

export class CustomResource extends BaseResource {
  async customOperation(params: any) {
    return this.request('GET', '/custom/endpoint', params);
  }
}

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Changelog

v1.0.0

• Initial release
• Complete TANSS API integration
• MCP compatibility
• AI agent support
• CLI interface
• n8n GUI integration
• Comprehensive error handling
• Dynamic command discovery
• OpenAPI-based validation

---

Made with ❤️ for the n8n and AI automation community