# freelo-mcp

A Model Context Protocol (MCP) server built with mcp-framework that provides integration with [Freelo](https://www.freelo.io) project management API.

## Features

This MCP server exposes tools for interacting with Freelo tasks, subtasks, and files:

- **freelo_get_task** - Get detailed information about a task including comments and attached files
- **freelo_list_task_subtasks** - List all subtasks with completion status
- **freelo_download_file** - Download files from task comments using UUID

## Quick Start

### 1. Get Your Freelo API Key

1. Log in to your [Freelo Dashboard](https://app.freelo.cz/dashboard)
2. Click on your avatar in the top right corner → **Settings**
3. Scroll to the bottom to find your **API Key**

### 2. Add to Claude Code

```bash
claude mcp add freelo-mcp -e FREELO_EMAIL=your-email@example.com -e FREELO_API_KEY=your-api-key -- npx -y @liquiddesign/freelo-mcp
```

That's it! You can now use Freelo tools in Claude Code.

## Alternative Setup

### Claude Code (Manual)

Add to your MCP settings (`~/.claude/settings.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "freelo-mcp": {
      "command": "npx",
      "args": ["-y", "@liquiddesign/freelo-mcp"],
      "env": {
        "FREELO_EMAIL": "your-email@example.com",
        "FREELO_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Claude Desktop

Add to Claude Desktop configuration file:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "freelo-mcp": {
      "command": "npx",
      "args": ["-y", "@liquiddesign/freelo-mcp"],
      "env": {
        "FREELO_EMAIL": "your-email@example.com",
        "FREELO_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Development

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Watch mode during development
npm run watch
```

For local development, configure Claude to use the built project directly:

```json
{
  "mcpServers": {
    "freelo-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/freelo-mcp/dist/index.js"],
      "env": {
        "FREELO_EMAIL": "your-email@example.com",
        "FREELO_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Project Structure

```
freelo-mcp/
├── src/
│   ├── tools/                           # MCP Tools
│   │   ├── FreeloGetTask.ts             # Get task details with comments & files
│   │   ├── FreeloListTaskSubtasks.ts    # List task subtasks
│   │   └── FreeloDownloadFile.ts        # Download files by UUID
│   ├── utils/
│   │   └── freeloApi.ts                 # Freelo API client & types
│   └── index.ts                         # Server entry point
├── package.json
├── tsconfig.json
└── CLAUDE.md                            # Claude Code instructions
```

## Available Tools

### 1. freelo_get_task

Get detailed information about a specific Freelo task, including all comments and attached files.

**Parameters:**
- `taskId` (number) - The unique ID of the task

**Returns:**
- Task name, description, priority, state
- Author and assignee information
- Dates (created, due, completed)
- Project and task list details
- Tags and time estimates
- Comments with content, author, timestamps, and attached files (with UUIDs)

**Example:**
```
Use freelo_get_task with taskId: 12345
```

### 2. freelo_list_task_subtasks

List all subtasks of a specific task with completion statistics.

**Parameters:**
- `taskId` (number) - The unique ID of the task

**Returns:**
- Array of subtasks with names, state, dates, author, assignee
- Statistics (total, completed, remaining, completion percentage)

**Example:**
```
Use freelo_list_task_subtasks with taskId: 12345
```

### 3. freelo_download_file

Download a file from Freelo using its UUID. File UUIDs are found in task comments (use `freelo_get_task` first).

**Parameters:**
- `fileUuid` (string) - The UUID of the file (from task comments)
- `filename` (string, optional) - Custom filename to save as

**Returns:**
- Downloaded file path (in system temp directory)
- File metadata (UUID, filename, size)

**Example:**
```
Use freelo_download_file with fileUuid: "550e8400-e29b-41d4-a716-446655440000"
```

## Adding New Tools

You can extend this MCP server with additional Freelo API tools:

```bash
# Add a new tool using mcp-framework CLI
mcp add tool my-tool

# Examples of additional Freelo tools you might create:
# - freelo_list_projects
# - freelo_create_task
# - freelo_add_comment
```

## Tool Development

Example tool structure:

```typescript
import { MCPTool } from "mcp-framework";
import { z } from "zod";

interface MyToolInput {
  message: string;
}

class MyTool extends MCPTool<MyToolInput> {
  name = "my_tool";
  description = "Describes what your tool does";

  schema = {
    message: {
      type: z.string(),
      description: "Description of this input parameter",
    },
  };

  async execute(input: MyToolInput) {
    // Your tool logic here
    return `Processed: ${input.message}`;
  }
}

export default MyTool;
```

## Publishing to npm

1. Update your package.json:
   - Ensure `name` is unique and follows npm naming conventions
   - Set appropriate `version`
   - Add `description`, `author`, `license`, etc.
   - Check `bin` points to the correct entry file

2. Build and test locally:
   ```bash
   npm run build
   npm link
   freelo-mcp  # Test your CLI locally
   ```

3. Login to npm (create account if necessary):
   ```bash
   npm login
   ```

4. Publish your package:
   ```bash
   npm publish
   ```

After publishing, users can add it to their Claude Desktop client (see below) or run it with npx.

## Usage with Claude Desktop

After building the project and configuring your credentials (see [Freelo API Setup](#freelo-api-setup)), restart Claude Desktop to load the MCP server.

You can then use the Freelo tools in your conversations with Claude:

**Example conversation:**
```
You: "Get details for Freelo task 12345"
Claude: [Uses freelo_get_task tool and returns task info with comments and files]

You: "Show me the subtasks"
Claude: [Uses freelo_list_task_subtasks tool and displays subtasks]

You: "Download the first file attachment"
Claude: [Uses freelo_download_file with the UUID from the task comments]
```

## Building and Testing

1. Make changes to your tools
2. Run `npm run build` to compile
3. The server will automatically load your tools on startup

## Learn More

### MCP Framework
- [MCP Framework GitHub](https://github.com/QuantGeekDev/mcp-framework)
- [MCP Framework Docs](https://mcp-framework.com)
- [Model Context Protocol](https://modelcontextprotocol.io)

### Freelo API
- [Freelo API Documentation](https://freelo.docs.apiary.io/) - Official API reference
- [Freelo API Help](https://help.freelo.io/help/api-klic/) - How to get your API key
- [Freelo Website](https://www.freelo.io) - Project management platform

## API Reference

This MCP server uses the Freelo REST API v1:

- **Base URL**: `https://api.freelo.io/v1`
- **Authentication**: HTTP Basic Auth (email:apiKey)
- **Response Format**: JSON
- **Current Support**: Read-only operations (GET endpoints)

For detailed API specifications, see the [official Freelo API documentation](https://freelo.docs.apiary.io/).

## Contributing

This is a personal project for Freelo API integration. Feel free to extend it with additional tools or improvements.

## License

MIT