# FlowAPI MCP Server

Model Context Protocol (MCP) server for integration with FlowAPI system operations.

## Overview

This MCP server provides system-level access to FlowAPI endpoints through Claude Code integration, enabling automated operations with sys_key authentication only. The server focuses on read operations and system queries that work reliably with system-level authentication.

## Features

- **System Authentication**: Uses X-SYS-KEY for system-level operations
- **Read-Only Focus**: Optimized for data retrieval and system queries
- **Typed API**: Full TypeScript type safety
- **Error Handling**: Comprehensive error handling and logging
- **Reliable Operations**: Only includes endpoints verified to work with sys_key auth

## Supported Operations

### Art & NFT Operations
- `list_arts` - Get list of arts with filters and pagination
- `get_art` - Get detailed art information by ID
- `get_recommended_arts` - Get recommended arts for discovery
- `list_art_collections` - List art collections with optional filters
- `get_art_collection` - Get collection details by ID

### User Management
- `search_users` - Search users with filters and pagination
- `get_user` - Get user information by various IDs (user_id, webapp_user_id, telegram_user_id, discord_user_id, camunda_user_id)
- `get_user_wallets` - Retrieve user wallet information

### Invite System
- `get_invited_wallets` - Get invited wallet addresses for blockchain integration
- `get_invited_wallets_by_token` - Get invited wallets for specific token

### External Workers & Strategies
- `list_external_workers` - List external worker configurations
- `get_external_worker` - Get external worker details
- `list_strategies` - List available strategies
- `get_strategy` - Get strategy details

### System Information
- `health_check` - Check API health and status
- `get_available_tools` - List all available MCP tools

## Installation

```bash
npm install
npm run build
```

## Configuration

Copy the example configuration:

```bash
cp .env.example .env
```

Edit `.env` with your FlowAPI configuration:

```env
# FlowAPI Configuration
FLOW_API_URL=https://your-flowapi-instance.com/api
FLOW_API_SYS_KEY=your-system-key-here

# Environment
NODE_ENV=production

# Logging
LOG_LEVEL=info

# MCP Server Configuration
MCP_SERVER_NAME=flowapi-server
MCP_SERVER_VERSION=1.0.0
```

## Usage

### Development
```bash
npm run dev
```

### Production
```bash
npm run build
npm start
```

### Testing
```bash
# Test all available endpoints
node dist/test-final.js
```

## Integration with Claude Code

Add to your Claude Code MCP configuration (`~/.claude/mcp_servers.json`):

```json
{
  "mcpServers": {
    "flowapi": {
      "command": "node",
      "args": ["/path/to/flowapi-mcp-server/dist/index.js"],
      "env": {
        "FLOW_API_URL": "https://your-flowapi-instance.com/api",
        "FLOW_API_SYS_KEY": "your-system-key-here",
        "NODE_ENV": "production"
      }
    }
  }
}
```

## Architecture

### Authentication Strategy
This server exclusively uses **system key authentication** (`X-SYS-KEY` header) for all operations. JWT-dependent endpoints have been removed to ensure reliability and consistency.

### Error Handling
- Comprehensive error responses with detailed information
- HTTP status code preservation
- Structured error messages for debugging

### Type Safety
- Full TypeScript implementation
- Zod schema validation for all inputs
- Strict API response typing

## API Examples

### List Arts with Filters
```typescript
// Get the first 10 arts
await client.getArts(10, 0, '{"active": true}');
```

### Search Users
```typescript
// Search for premium users
await client.searchUsers({ 
  is_premium: true, 
  page: 1, 
  page_size: 10 
});
```

### Get User Information
```typescript
// Get user by different ID types
await client.getUserBy({ user_id: "uuid-here" });
await client.getUserBy({ camunda_user_id: "camunda-id" });
await client.getUserBy({ webapp_user_id: "webapp-uuid" });
```

## Development Notes

### Removed Features
The following endpoints were removed due to JWT authentication requirements:
- `create_art` - Requires user context via JWT
- `update_art` - Requires user ownership validation
- `create_art_collection` - Requires user authentication
- `get_next_arts` - Requires user personalization
- `get_arts_history` - Requires user context

### Adding New Endpoints
1. Add the endpoint method to `FlowApiClient`
2. Create the tool definition in appropriate tool file
3. Add the handler in the tool's `handle` function
4. Update type definitions if needed
5. Test with sys_key authentication

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Ensure all tests pass: `npm test`
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions, please use the GitHub Issues page.