fenix-mcp 2.5.0

Fênix Cloud MCP server implemented in Python

Fenix MCP Server
Python MCP server for Fenix Cloud API integration

Quick Start • Installation • Configuration • Structure

---

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

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)

pipx install fenix-mcp

With pip

pip install --user fenix-mcp

Upgrade

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

---

Configuration

MCP Client Setup

Claude Code — ~/.claude/config.toml

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

Cursor — ~/.cursor/mcp.json

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

VS Code / Windsurf — settings.json

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

---

Environment Variables

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 for reference.

HTTP Transport

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:

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

---

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

fenix_mcp/ — Package Structure

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)

---

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

# 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:

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

command not found: fenix-mcp

Add scripts directory to PATH:

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

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

401 Unauthorized

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

Run HTTP and STDIO simultaneously

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

---

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