fms-odata-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

FileMaker Server OData MCP is a Model Context Protocol (MCP) server that exposes FileMaker Server's OData 4.01 API as MCP tools for use by AI agents (Claude Desktop, Windsurf, Cursor, Cline). It is published as an npm package (fms-odata-mcp).

Commands

# Build
npm run build          # Compile TypeScript to dist/
npm run watch          # Watch mode

# Run
npm start              # Run compiled dist/index.js
npm run dev            # Build then run

# Test
npm test               # Run unit tests (tests/unit/**/*.test.ts)
npm run test:watch     # Watch mode
npm run test:coverage  # With coverage report

# Docker (convenience script — handles BOM stripping, build, and restart)
./start.sh             # Build image and start HTTP container from .env

To run a single test file:

npx jest tests/unit/odata-client.test.ts

Manual stdio test (no persistent container needed)

bash -c '{
  echo '\''{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'\''; sleep 1
  echo '\''{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}'\''; sleep 1
  echo '\''{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"fm_odata_connect","arguments":{"server":"https://FM_SERVER","database":"DB","user":"USER","password":"PASS","verifySsl":false}}}'\''; sleep 2
  echo '\''{"jsonrpc":"2.0","method":"tools/call","id":3,"params":{"name":"fm_odata_list_tables","arguments":{}}}'\''; sleep 5
} | docker run --rm -i --env-file .env fms-odata-mcp:latest'

Architecture

Three-layer architecture communicating via the MCP protocol:

MCP Client (Claude, Windsurf, etc.)
        ↓ MCP protocol
Transport Layer  (src/transport.ts, src/simple-http-transport.ts)
        ↓ tool calls
Tools Handler    (src/tools/index.ts → odata.ts / connection.ts / configuration.ts)
        ↓ HTTP requests
OData Client     (src/odata-client.ts)
        ↓ Basic Auth + HTTP/HTTPS
FileMaker Server OData 4.01 API