fenix-mcp 2.8.3
Fênix Cloud MCP server implemented in Python
Requires Python: >=3.10

<p align="center">
  <img src="https://fenix.devshire.app/logos/logo_fenix.png" alt="Fenix MCP" width="200" />
</p>

<p align="center">
  <strong>Fenix MCP Server</strong><br/>
  Python MCP server for Fenix Cloud API integration
</p>

<p align="center">
  <a href="https://pypi.org/project/fenix-mcp/"><img src="https://img.shields.io/pypi/v/fenix-mcp.svg" alt="PyPI"></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"></a>
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> •
  <a href="#installation">Installation</a> •
  <a href="#configuration">Configuration</a> •
  <a href="#project-structure">Structure</a>
</p>

---

## Overview

Fenix MCP connects MCP-compatible clients (Claude Code, Cursor, Windsurf, VS Code, etc.) directly to the Fenix Cloud APIs. Every tool invocation hits the live backend—no outdated snapshots or hallucinated IDs.

**Available Tools:**
- `knowledge` — Documentation CRUD, work items, modes, rules
- `productivity` — TODO management
- `intelligence` — Memories and smart operations
- `user_config` — User configuration documents
- `initialize` — Personalized setup
- `health` — Backend health check

---

## Quick Start

```bash
pipx install fenix-mcp                    # Install
fenix-mcp --pat <your-token>              # Run (STDIO mode)
```

---

## Requirements

| Requirement | Version |
|-------------|---------|
| Python | 3.10+ |
| Fenix PAT Token | Required |
| MCP Client | Claude Code, Cursor, Windsurf, VS Code, etc. |

---

## Installation

### With pipx (recommended)

```bash
pipx install fenix-mcp
```

### With pip

```bash
pip install --user fenix-mcp
```

### Upgrade

```bash
pipx upgrade fenix-mcp
# or
pip install --upgrade fenix-mcp
```

---

## Configuration

### MCP Client Setup

<details>
<summary><strong>Claude Code</strong> — ~/.claude/config.toml</summary>

```toml
[mcp_servers.fenix]
command = "fenix-mcp"
args = ["--pat", "your-token"]
```

</details>

<details>
<summary><strong>Cursor</strong> — ~/.cursor/mcp.json</summary>

```json
{
  "mcpServers": {
    "fenix": {
      "command": "fenix-mcp",
      "args": ["--pat", "your-token"],
      "disabled": false
    }
  }
}
```

</details>

<details>
<summary><strong>VS Code / Windsurf</strong> — settings.json</summary>

```json
{
  "modelContextProtocol.mcpServers": {
    "fenix": {
      "command": "fenix-mcp",
      "args": ["--pat", "your-token"]
    }
  }
}
```

</details>

---

<details>
<summary><strong>Environment Variables</strong></summary>

| Variable | Description | Default |
|----------|-------------|---------|
| `FENIX_API_URL` | Fenix Cloud API base URL | `https://fenix-api.devshire.app` |
| `FENIX_PAT_TOKEN` | Token (alternative to `--pat`) | empty |
| `FENIX_TRANSPORT_MODE` | `stdio`, `http`, or `both` | `stdio` |
| `FENIX_HTTP_HOST` | HTTP transport host | `127.0.0.1` |
| `FENIX_HTTP_PORT` | HTTP transport port | `5003` |
| `FENIX_LOG_LEVEL` | Log level (`DEBUG`, `INFO`, etc.) | `INFO` |

See [`.env.example`](./.env.example) for reference.

</details>

<details>
<summary><strong>HTTP Transport</strong></summary>

```bash
export FENIX_TRANSPORT_MODE=http
export FENIX_HTTP_PORT=5003
fenix-mcp --pat <your-token>
```

JSON-RPC endpoint: `http://127.0.0.1:5003/jsonrpc`

Run both STDIO and HTTP:

```bash
export FENIX_TRANSPORT_MODE=both
fenix-mcp --pat <your-token>
```

</details>

---

## Project Structure

```
fenix-mcp-py/
├── fenix_mcp/                  # Main package
│   ├── main.py                 # Entry point (CLI)
│   ├── application/            # Use cases and services
│   ├── domain/                 # Business entities
│   ├── infrastructure/         # External integrations (API, transport)
│   └── interface/              # MCP protocol handlers
├── tests/                      # Test suite
├── docs/                       # Documentation
├── pyproject.toml              # Project configuration
└── .env.example                # Environment template
```

<details>
<summary><strong>fenix_mcp/</strong> — Package Structure</summary>

| Directory | Responsibility |
|-----------|----------------|
| `main.py` | CLI entry point, argument parsing, server bootstrap |
| `application/` | Use cases, handlers for each MCP tool |
| `domain/` | Business entities, DTOs, validation |
| `infrastructure/` | API client, HTTP transport, logging |
| `interface/` | MCP protocol implementation, tool registration |

### Architecture

```
MCP Client → interface/ → application/ → infrastructure/ → Fenix API
                              ↓
                          domain/
                        (entities)
```

</details>

---

## Tech Stack

| Layer | Technology |
|-------|------------|
| Runtime | Python 3.10+ |
| Validation | Pydantic 2 |
| HTTP | aiohttp, requests |
| Config | pydantic-settings |
| Testing | pytest, pytest-asyncio |
| Linting | flake8, black, mypy |

---

## Development

### Setup

```bash
# Clone and install
git clone <repo>
cd fenix-mcp-py
pip install -e .[dev]
```

### Scripts

| Command | Description |
|---------|-------------|
| `pytest` | Run tests |
| `pytest --cov=fenix_mcp` | Run with coverage |
| `black fenix_mcp/ tests/` | Format code |
| `flake8 fenix_mcp/ tests/` | Lint |
| `mypy fenix_mcp/` | Type check |

### Commit Convention

Follow [Conventional Commits](https://www.conventionalcommits.org/):

| Prefix | Description | Version Bump |
|--------|-------------|--------------|
| `fix:` | Bug fixes | Patch |
| `feat:` | New features | Minor |
| `BREAKING CHANGE:` | Breaking changes | Major |
| `chore:` | Maintenance | None |
| `docs:` | Documentation | None |

---

## CI/CD

| Platform | Usage |
|----------|-------|
| GitHub Actions | Tests, lint, build on push/PR to main |
| Semantic Release | Auto-version based on commits |
| PyPI | Package distribution |

---

## Troubleshooting

<details>
<summary><code>command not found: fenix-mcp</code></summary>

Add scripts directory to PATH:

```bash
# macOS/Linux
export PATH="$PATH:~/.local/bin"

# Windows
# Add %APPDATA%\Python\Python311\Scripts to PATH
```

</details>

<details>
<summary><code>401 Unauthorized</code></summary>

1. Check `--pat` or `FENIX_PAT_TOKEN` is set correctly
2. Regenerate token in Fenix Cloud if expired

</details>

<details>
<summary>Run HTTP and STDIO simultaneously</summary>

```bash
export FENIX_TRANSPORT_MODE=both
fenix-mcp --pat <your-token>
```

</details>

---

## Security

- Store tokens securely (keychain, `pass`, `.env`)
- Never commit secrets to git
- Revoke tokens when no longer needed
- Use `pipx` to isolate from global Python

---

## Useful Links

| Resource | URL |
|----------|-----|
| PyPI | https://pypi.org/project/fenix-mcp/ |
| Fenix Cloud | https://fenix.devshire.app |
| MCP Protocol | https://modelcontextprotocol.io |