# MCP Presets

Pre-configured MCP (Model Context Protocol) adapters for various project management and collaboration tools.

## Available Presets

### Jira (`jira.json`)

Connect to Atlassian Jira for loading issues and context.

**Setup:**
```bash
aiflow init --adapter jira
```

**Required Environment Variables:**
- `JIRA_API_TOKEN` — Your Jira API token
- `JIRA_EMAIL` — Your Jira account email
- `JIRA_DOMAIN` — Your Jira domain (e.g., "company" in company.atlassian.net)

**Get API Token:**
1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Create new API token
3. Copy the token

**Usage:**
```bash
aiflow use JIRA-123
# Loads issue JIRA-123 from your Jira instance
```

### Backlog (`backlog.json`)

Connect to Nulab Backlog for loading tasks and context.

**Setup:**
```bash
aiflow init --adapter backlog
```

**Required Environment Variables:**
- `BACKLOG_API_KEY` — Your Backlog API key
- `BACKLOG_SPACE_KEY` — Your Backlog space key

**Get API Key:**
1. Log in to Backlog
2. Go to Personal Settings → API Settings
3. Generate new API token

**Usage:**
```bash
aiflow use BACKLOG-456
# Loads task from your Backlog instance
```

### Figma (`figma.json`)

Connect to Figma via REST API to read design files and generate components.

**When to use:** Default choice. Works anywhere — no Desktop app required.

**Setup:**
```bash
aiflow init --adapter figma
```

**Required Environment Variables:**
- `FIGMA_API_TOKEN` — Your Figma Personal Access Token

**Get API Token:**
1. Go to https://www.figma.com/settings → Security → Personal access tokens
2. Create a new token with File content (read) scope
3. Copy the token

**Tools provided by `figma-developer-mcp`:**
- `get_figma_data(fileKey, nodeId, depth)` — fetch node layout, styles, components
- `download_figma_images(fileKey, nodes, localPath)` — export images

**Usage:**
```
Generate component from Figma:
https://www.figma.com/design/XXXXX/App?node-id=123-456
```

See: [Figma workflow guide](../../docs/common/workflows/figma.md)

---

### Figma Desktop (`figma-desktop.json`)

Connect via the official Figma MCP server. Requires Figma Desktop app open.

**When to use:** When your team prefers the official Figma tooling and has Desktop app licenses.
**When NOT to use:** CI environments, headless servers, team members without Desktop licenses.

**Setup:**
```bash
aiflow init --adapter figma-desktop
```

**Requirements:**
- Figma Desktop app installed
- A Figma file open in Desktop when invoking the skill
- No API token needed — uses Desktop session

**Tools provided by `@figma/mcp-server`:**
- `get_figma_data(fileKey, nodeId)` — fetch design data for open file
- `get_node_children(nodeId)` — traverse component tree
- `get_local_components()` — list components in the open file

| | `figma` (REST API) | `figma-desktop` (Official) |
|---|---|---|
| Needs Desktop app | No | Yes (must be open) |
| Auth | API Token | Desktop session |
| Works in CI | Yes | No |
| Access scope | Full REST API | Currently open file |

See: [Figma workflow guide](../../docs/common/workflows/figma.md)

---

### Google Sheets (`google-sheets.json`)

Connect to Google Sheets for loading task context.

**Setup:**
```bash
aiflow init --adapter google-sheets
```

**Required Environment Variables:**
- `GOOGLE_SHEETS_CREDS` — Path to service account JSON

**Get Credentials:**
1. Create Google Cloud project
2. Enable Sheets API
3. Create service account
4. Download JSON credentials
5. Store securely and set path

**Usage:**
```bash
aiflow use SHEET-A1:D5
# Loads data from Google Sheet
```

## Creating Custom Presets

To add a new MCP adapter:

1. Create `<adapter-name>.json`:

```json
{
  "mcpServers": {
    "<adapter-name>": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-<adapter-name>"
      ],
      "env": {
        "ENV_VAR_1": "{{PLACEHOLDER}}",
        "ENV_VAR_2": "{{PLACEHOLDER}}"
      }
    }
  }
}
```

2. Document in this README

3. Users can install with:
```bash
aiflow init --adapter <adapter-name>
```

## Validators

Each preset should be validated during `aiflow init`:

- ✓ Environment variables set
- ✓ API connectivity working
- ✓ Proper permissions configured

## Best Practices

1. **Use placeholders** — {{VAR_NAME}} for env variables
2. **Document setup** — Include step-by-step guide
3. **Provide examples** — Show usage patterns
4. **Handle errors** — Clear error messages if setup fails
5. **Support multiple instances** — Allow team variations

## Security

- **Never commit credentials** — Use environment variables
- **Use secure storage** — Store API tokens securely
- **Rotate tokens** — Regularly update API tokens
- **Restrict permissions** — Use minimal required permissions
- **Audit access** — Monitor who accesses what

---

For more info: See [Configuration Guide](../../docs/configuration.md)