Technical Reference

MCP Integration

Model Context Protocol server implementation and available tools.

What is MCP

Model Context Protocol (MCP) is an open standard for connecting language models to external tools and data sources. This installation provides an MCP server that exposes installation capabilities as callable tools.

MCP Server URL

 # Development
ws://localhost:4321/mcp

# Production
wss://your-domain.com/mcp 

Server configuration

Configure the MCP server in environment variables and claude.json configuration.

Environment variables

 .env 
 # Enable MCP server
MCP_ENABLED=true

# Server port (default: 4322)
MCP_PORT=4322

# Authentication (optional)
MCP_AUTH_TOKEN=your-secret-token 

Claude Code configuration

 claude.json 
 {
  "mcpServers": {
    "installation": {
      "command": "node",
      "args": ["mcp-server.js"],
      "env": {
        "MCP_PORT": "4322"
      }
    }
  }
} 

Docker Compose integration

 docker-compose.yml 
 services:
  mcp-server:
    build: .
    command: node mcp-server.js
    ports:
      - "4322:4322"
    environment:
      - MCP_ENABLED=true
      - MCP_PORT=4322
    networks:
      - caddy 

Available tools

The MCP server exposes these tools for LLM interaction.

Tool	Purpose	Parameters
`create_share`	Create shareable content	`content`, `options`
`get_share`	Retrieve shared content	`id`
`list_shares`	List all shares	`limit`, `offset`
`get_installation_info`	Retrieve installation metadata	None
`search_content`	Search installation content	`query`, `type`

Tool: create_share

Creates a shareable content item and returns the URL.

Parameters

Parameter	Type	Required	Description
`content`	object	Yes	Content object with `type` and `body`
`options`	object	No	Optional configuration (expires, password, maxViews)

Example invocation

 {
  "name": "create_share",
  "arguments": {
    "content": {
      "type": "text",
      "body": "Example content to share"
    },
    "options": {
      "expires": "2024-12-31T23:59:59Z",
      "maxViews": 100
    }
  }
} 

Response

 {
  "id": "sh_abc123xyz",
  "url": "https://your-domain.com/s/abc123xyz",
  "created": "2024-01-16T10:00:00Z"
} 

Tool: get_installation_info

Retrieves metadata about the installation including version, configuration, and capabilities.

Parameters

No parameters required.

Example invocation

 {
  "name": "get_installation_info"
} 

Response

 {
  "name": "Artisan Digital Installation",
  "version": "1.0.0",
  "capabilities": [
    "share",
    "interactive-components",
    "pwa-support"
  ],
  "configuration": {
    "atelierMode": "prod",
    "ambientEffects": true,
    "pwaBadging": true
  },
  "uptime": 86400,
  "lastDeployed": "2024-01-16T10:00:00Z"
} 

Tool: search_content

Searches installation content by query string and optional type filter.

Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Search query string
`type`	string	No	Filter by type: `page`, `component`, `share`

Example invocation

 {
  "name": "search_content",
  "arguments": {
    "query": "digital storytelling",
    "type": "page"
  }
} 

Response

 {
  "results": [
    {
      "type": "page",
      "title": "Digital Storytelling",
      "url": "/experience/digital-storytelling",
      "excerpt": "Crafting compelling narratives for your installation...",
      "score": 0.95
    }
  ],
  "total": 1,
  "query": "digital storytelling"
} 

Authentication

MCP server supports optional token-based authentication for secure tool access.

Configure authentication

 .env 
 # Set authentication token
MCP_AUTH_TOKEN=your-secure-token-here

# Disable authentication (development only)
MCP_AUTH_TOKEN= 

Client configuration

 claude.json 
 {
  "mcpServers": {
    "installation": {
      "command": "node",
      "args": ["mcp-server.js"],
      "env": {
        "MCP_AUTH_TOKEN": "your-secure-token-here"
      }
    }
  }
} 

Error handling

MCP tool errors follow standard JSON-RPC 2.0 error format.

Error response format

 {
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid parameters",
    "data": {
      "parameter": "content",
      "reason": "Required parameter missing"
    }
  }
} 

Common error codes

Code	Message	Meaning
`-32600`	Invalid Request	Malformed JSON-RPC request
`-32601`	Method not found	Tool name does not exist
`-32602`	Invalid params	Missing or invalid parameters
`-32603`	Internal error	Server-side error during execution

Development and testing

Test MCP tools during development using the inspector and manual invocation.

Start MCP server in development mode

 # Start with debug logging
MCP_DEBUG=true node mcp-server.js

# Expected output:
# MCP Server listening on ws://localhost:4322
# Tools available: create_share, get_share, list_shares, get_installation_info, search_content 

Test tool invocation with wscat

 # Install wscat
npm install -g wscat

# Connect to MCP server
wscat -c ws://localhost:4322

# Send tool invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_installation_info"
  }
} 

MCP Inspector

Use the official MCP Inspector for visual debugging:

npx @modelcontextprotocol/inspector node mcp-server.js

Opens a web UI at http://localhost:5173 for interactive tool testing.

Adding custom tools

Extend the MCP server with custom tools specific to your installation.

Define tool schema

 mcp-server.js 
 // mcp-server.js
import { FastMCP } from 'fastmcp';

const mcp = new FastMCP('installation');

// Define custom tool
mcp.addTool({
  name: 'custom_action',
  description: 'Performs a custom action on the installation',
  parameters: {
    type: 'object',
    properties: {
      action: {
        type: 'string',
        description: 'Action to perform'
      },
      data: {
        type: 'object',
        description: 'Action data payload'
      }
    },
    required: ['action']
  },
  handler: async (params) => {
    const { action, data } = params;

    // Implement custom logic
    switch (action) {
      case 'example':
        return { success: true, result: 'Example action completed' };
      default:
        throw new Error(`Unknown action: ${action}`);
    }
  }
});

mcp.start(); 