RCC SP

A Model Context Protocol (MCP) server for FileMaker databases, providing comprehensive database access through dynamic script discovery, full CRUD operations, and OData query capabilities with flexible authentication methods.

Features

🎯 Core Capabilities

• Dynamic Script Discovery: Automatically discovers and exposes FileMaker scripts using the GetToolList pattern
• Full CRUD Operations: Create, Read, Update, Delete records across any layout
• OData Support: Advanced querying with filtering, sorting, and pagination
• Flexible Authentication: Supports API key, basic auth, and Otto proxy authentication
• Multi-Database Ready: Configurable for any FileMaker server deployment

🔧 Key Advantages

• Graceful Degradation: Works with or without GetToolList script - CRUD always available
• TypeScript First: Full type safety and modern development experience
• Caching & Performance: Intelligent caching for sessions, data, and script discovery
• Production Ready: Comprehensive error handling, logging, and configuration validation
• Web App Ready: Designed for integration with web applications and chatbots

Quick Start

Prerequisites

• Node.js 18+
• Access to a FileMaker Server with Data API enabled
• Valid authentication credentials (API key, username/password, or Otto proxy)

Installation

# Install dependencies
npm install

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your FileMaker server details

# Build and start
npm run build
npm start

Configuration

The MCP server is configured via environment variables in the .env file:

# Example Database Configuration
FM_NAME=YourDatabase
FM_HOST=https://your-filemaker-server.com
FM_DATABASE=YourDatabaseName

# Authentication (choose one method)
FM_AUTH_TYPE=basic
FM_USERNAME=your_username
FM_PASSWORD=your_password

# Or use API key authentication
# FM_AUTH_TYPE=apikey
# FM_API_KEY=your-api-key-here

# Layouts and Features
FM_LAYOUTS=API_Client,API_Project,API_Task
FM_DEFAULT_LAYOUT=API_Client
FM_ENABLE_SCRIPT_DISCOVERY=true
FM_ENABLE_ODATA=true
FM_DEFAULT_API=data_api

# Logging and MCP Settings
LOG_LEVEL=info
MCP_CLEAR_CACHE_ON_STARTUP=true

GetToolList Script Implementation

For dynamic script discovery, implement this FileMaker script named "GetToolList":

# GetToolList Script (FileMaker)
# Purpose: Return JSON describing available scripts for MCP

Exit Script [
  Text Result: 
  "{
    \"tools\": [
      {
        \"name\": \"send_email\",
        \"description\": \"Send email notification to client\",
        \"parameters\": [
          {\"name\": \"client_id\", \"type\": \"string\", \"required\": true, \"description\": \"Client record ID\"},
          {\"name\": \"message\", \"type\": \"string\", \"required\": true, \"description\": \"Email message content\"},
          {\"name\": \"urgent\", \"type\": \"boolean\", \"required\": false, \"description\": \"Mark as urgent\"}
        ]
      },
      {
        \"name\": \"generate_report\",
        \"description\": \"Generate project status report\", 
        \"parameters\": [
          {\"name\": \"project_id\", \"type\": \"string\", \"required\": true, \"description\": \"Project ID\"},
          {\"name\": \"include_financials\", \"type\": \"boolean\", \"required\": false, \"description\": \"Include financial data\"}
        ]
      }
    ]
  }"
]

Usage Examples

With Claude Desktop

Add to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "filemaker-enhanced": {
      "command": "node",
      "args": ["/path/to/MCP-Claude-FileMaker-Enhanced/dist/index.js"],
      "env": {
        "MCP_CONFIG_FILE": "/path/to/config/databases.json"
      }
    }
  }
}

Available MCP Tools

The server automatically provides these tools to Claude:

CRUD Operations

• fm_find_records - Search and retrieve records
• fm_get_record - Get single record by ID
• fm_create_record - Create new record
• fm_update_record - Update existing record
• fm_delete_record - Delete record

OData Queries (if enabled)

• fm_odata_query - Advanced filtering and sorting
• fm_odata_metadata - Get database schema info

Dynamic Scripts (via GetToolList)

• Custom script tools based on your GetToolList implementation
• Parameters automatically validated and typed

Management Tools

• fm_list_layouts - Get available layouts
• fm_get_database_info - Database metadata
• fm_health_check - Connection status

Advanced Configuration

Authentication Methods

# Basic Authentication
FM_AUTH_TYPE=basic
FM_USERNAME=username
FM_PASSWORD=password

# API Key Authentication
FM_AUTH_TYPE=apikey  
FM_API_KEY=your-api-key

# Otto Proxy Authentication
FM_AUTH_TYPE=otto
FM_OTTO_URL=https://otto-proxy.com

Caching Configuration

# Session cache (13 minutes default)
SESSION_TTL=780

# Data cache (14 minutes default) 
DATA_TTL=840

# Script discovery cache (30 minutes default)
SCRIPT_TTL=1800

Logging Options

# Log level: error, warn, info, debug
LOG_LEVEL=info

# Optional log file (defaults to console)
LOG_FILE=/var/log/filemaker-mcp.log

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Enhanced FileMaker MCP                    │
├─────────────────────────────────────────────────────────────┤
│  Claude Desktop  ←→  MCP Protocol  ←→  FileMaker Server     │
├─────────────────────────────────────────────────────────────┤
│                        Components                           │
│  • ConfigManager      - Multi-database configuration       │
│  • AuthManager        - Flexible authentication           │ 
│  • DataClient         - CRUD operations with caching      │
│  • ODataClient        - Advanced querying capabilities    │
│  • ScriptDiscovery    - Dynamic tool generation           │
│  • Logger             - Comprehensive logging             │
└─────────────────────────────────────────────────────────────┘

Key Design Decisions

1. GetToolList Pattern: Curated script exposure with graceful fallback
2. TypeScript First: Full type safety throughout the codebase
3. Caching Strategy: Multi-level caching for optimal performance
4. Error Resilience: Comprehensive error handling and recovery
5. Configuration Flexibility: Support for simple and complex deployments

Troubleshooting

Common Issues

Connection Errors

# Check FileMaker Server status
curl -k https://your-server.com/fmi/data/v1/databases

# Verify credentials
npm run test -- --grep "authentication"

Script Discovery Issues

# Test GetToolList script directly in FileMaker
# Should return valid JSON with tools array

# Check script discovery cache
LOG_LEVEL=debug npm start

Performance Issues

# Enable query logging
DEBUG_FILEMAKER_QUERIES=true npm start

# Check cache hit rates
LOG_LEVEL=info npm start | grep "cache"

Development

Project Structure

src/
├── core/
│   ├── auth.ts           # Authentication management
│   ├── config.ts         # Configuration loading/validation  
│   ├── data-client.ts    # FileMaker Data API client
│   └── logger.ts         # Logging utilities
├── adapters/
│   ├── odata.ts          # OData query adapter
│   └── script-discovery.ts # Dynamic script discovery
├── types/
│   └── filemaker.ts      # TypeScript type definitions
└── index.ts              # Main MCP server

config/
├── databases.json        # Multi-database configuration
└── sample-*.json         # Configuration examples

docs/
├── getToolList.md        # GetToolList implementation guide
└── examples/             # Usage examples and FileMaker scripts

Building and Testing

# Development with hot reload  
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Lint and format
npm run lint
npm run format

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation: Full docs in the /docs folder
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Acknowledgments

• Anthropic for the Model Context Protocol specification
• FileMaker Community for FileMaker Data API best practices
• ProofGeist for FileMaker API patterns and inspiration
• Original MCP Contributors for foundational MCP implementation patterns