Local Dev

Local Development — Running and Testing the Server

This skill covers building, running, testing, and debugging the photofield server on your local machine.

All tool invocation, server management, and API calls go through ./tools/agent.sh — a unified harness that handles the server lifecycle, generic HTTP calls, and MCP tool invocation with session management, SSE parsing, and named-arg parsing.

Verbose Flag

The harness accepts --verbose, -v, and -V. Any of these can be placed directly after ./tools/agent.sh:

./tools/agent.sh --verbose mcp call get_photo --file_id 1
./tools/agent.sh -v mcp call get_photo --file_id 1
./tools/agent.sh -V mcp call get_photo --file_id 1

Or avoid the flag entirely via environment variable:

AGT_VERBOSE=1 ./tools/agent.sh mcp call get_photo --file_id 1

1. Build

go build -o photofield .

Kill any old instance before rebuilding:

./tools/agent.sh server kill

2. Configuration

The server reads data/configuration.yaml. Without it, collections point to empty directories.

Minimal setup:

mkdir -p data
cat > data/configuration.yaml <<EOF
collections:
  - name: test
    dirs:
      - docs/assets
EOF

3. Server Lifecycle

Use ./tools/agent.sh server <command> to manage the server process:

# Start (auto-detects if already running)
./tools/agent.sh server start

# Stop gracefully (uses PID file)
./tools/agent.sh server stop

# Restart
./tools/agent.sh server restart

# Check status (shows PID and port listeners)
./tools/agent.sh server status

# Aggressive kill (PID file + all port listeners including exiftool)
./tools/agent.sh server kill

How it works: server start launches the binary with nohup and writes a PID file to data/agent.pid. It then polls the server endpoint until ready (up to 30s). server stop reads the PID file and sends SIGTERM. server kill sends SIGKILL to the PID and anything else listening on the port.

Important: The server does not auto-scan. After starting, run a scan:

./photofield -scan test
# or from another directory:
AGT_BIN=/path/to/photofield ./tools/agent.sh server start && ./photofield -scan test

The server listens on port 8080 by default (override with AGT_PORT).

Note: With AGT_START=true (the default), mcp call, mcp quick, and mcp shell will auto-start the server if it is not already running. The server start, server stop, server restart, server status, and server kill commands manage the process regardless of AGT_START.

Stale PID cleanup

If the server crashes without a clean shutdown, the PID file may become stale. The harness auto-detects this: server start will clean up a dead PID file and launch a new instance. server status also removes stale entries.

4. MCP Tool Calls

Use ./tools/agent.sh mcp to call MCP tools. The harness handles the session handshake (initialize + initialized notification), session ID extraction from response headers, SSE response parsing, and named-arg to JSON conversion.

Tool commands

# Call a tool with JSON args
./tools/agent.sh mcp call list_collections '{}'

# Call with named args (auto-detects --key val pairs)
./tools/agent.sh mcp call search_photos --query 'beach' --collection_id 'test' --limit 3

# Verbose mode — shows full raw JSON response
./tools/agent.sh --verbose mcp call get_photo --file_id 1 --w 200

# Smoke test (calls list_collections by default)
./tools/agent.sh mcp quick

# Smoke test with a specific tool
./tools/agent.sh mcp quick get_photo --file_id 1

# Interactive REPL
./tools/agent.sh mcp shell

Argument modes

Named args are auto-converted to JSON: numbers stay numeric, true/false become booleans, null stays null, everything else is quoted as strings. agent.sh auto-detects the named-arg mode when the first token starts with --, so no explicit -- -- boundary is ever needed.

Output

Non-verbose mode shows a clean summary:

✓ list_collections — 22 items
✓ events — 19 events
✓ get_photo

Errors show with a red ✗ and the error message. Set --verbose (see Verbose Flag above) for full raw JSON on every call.

Output streams: The log_* helpers (ℹ, ▶) go to stderr. Tool result summaries (✓, ✗) and raw JSON output go to stdout. This lets you pipe tool results: ./tools/agent.sh mcp call list_collections '{}' | jq '.collections'.

From another directory

AGT_BIN=/path/to/photofield ./tools/agent.sh mcp call list_collections '{}'
AGT_URL=http://remote-host:9000/mcp ./tools/agent.sh mcp call list_collections '{}'

5. Generic API Calls

Use ./tools/agent.sh api for arbitrary HTTP calls to any server endpoint. This is useful for testing non-MCP routes, debugging, or calling endpoints that don't have a dedicated tool.

# GET request (health check)
./tools/agent.sh api GET http://localhost:8080/health

# POST with JSON body
./tools/agent.sh api POST http://localhost:8080/api/collections \
  '{"name":"my-collection","dirs":["/path/to/photos"]}'

# POST with named args (auto-constructs JSON body)
./tools/agent.sh api POST http://localhost:8080/api/collections \
  --name my-collection --dirs /path/to/photos

# PUT / DELETE
./tools/agent.sh api DELETE http://localhost:8080/api/collections/test

The output shows the HTTP status code, pretty-printed JSON when possible, and the response body (truncated if over 500 chars). Note: AGT_VERBOSE=1 does not currently change the truncation behavior for API calls.