# FileMaker MCP Server - RCC Starting Point

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

```bash
# 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:

```bash
# 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"**:

```javascript
# 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:

```json
{
  "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

```bash
# 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

```bash
# 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

```bash
# 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**
```bash
# Check FileMaker Server status
curl -k https://your-server.com/fmi/data/v1/databases

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

**Script Discovery Issues**
```bash
# Test GetToolList script directly in FileMaker
# Should return valid JSON with tools array

# Check script discovery cache
LOG_LEVEL=debug npm start
```

**Performance Issues**
```bash
# 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

```bash
# 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](LICENSE) file for details.

## Support

- **Documentation**: Full docs in the `/docs` folder
- **Issues**: [GitHub Issues](https://github.com/datacraftdevelopment/MCP-Claude-FileMaker-Enhanced/issues)  
- **Discussions**: [GitHub Discussions](https://github.com/datacraftdevelopment/MCP-Claude-FileMaker-Enhanced/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