fenix-mcp 0.1.0__tar.gz

fenix_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: fenix-mcp
+Version: 0.1.0
+Summary: Fênix Cloud MCP server implemented in Python
+Author: Fenix Inc
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.5
+Requires-Dist: requests>=2.31
+Requires-Dist: urllib3>=2.0
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: pydantic-settings>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# Fênix MCP — Live Access to Fênix Cloud Data
+
+[![PyPI](https://img.shields.io/pypi/v/fenix-mcp.svg)](https://pypi.org/project/fenix-mcp/) [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+**Fênix MCP** connects MCP-compatible clients (Codex, Cursor, Context7, Windsurf, VS Code, etc.) directly to the Fênix Cloud APIs. Every tool invocation hits the live backend—no outdated snapshots or hallucinated IDs.
+
+## ❌ Without Fênix MCP
+
+- Manual lookups in the web console slow you down
+- Agents fabricate document status, IDs, or team data
+- Automation workflows stall on stale information
+
+## ✅ With Fênix MCP
+
+- Real-time API calls over STDIO or HTTP
+- Rich toolset: documentation CRUD, work items, modes, rules, TODOs, memories
+- Built for multi-user environments and multiple MCP clients
+
+## 🛠 Requirements
+
+- Python 3.10 or newer
+- Fênix Cloud Personal Access Token (`FENIX_PAT_TOKEN`)
+- Any MCP client (Codex, Cursor, VS Code MCP, etc.)
+
+## 🚀 Installation
+
+### With `pipx` (recommended)
+
+```bash
+pipx install fenix-mcp
+```
+
+### With `pip`
+
+```bash
+pip install --user fenix-mcp
+```
+
+To upgrade:
+
+```bash
+pipx upgrade fenix-mcp
+# or
+pip install --upgrade fenix-mcp
+```
+
+## ▶️ Quick Start
+
+Launch the STDIO server by providing your token (or set `FENIX_PAT_TOKEN` beforehand):
+
+```bash
+fenix-mcp --pat <your-token>
+```
+
+The command accepts all flags supported by `fenix_mcp.main` and responds over STDIO, ready for MCP clients.
+
+## ⚙️ MCP Client Configuration
+
+### Codex CLI (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers.fenix]
+command = "fenix-mcp"
+args = ["--pat", "your-token"]
+```
+
+### Cursor (`~/.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "fenix": {
+      "command": "fenix-mcp",
+      "args": ["--pat", "your-token"],
+      "disabled": false
+    }
+  }
+}
+```
+
+### VS Code (Insiders) / Windsurf (`settings.json`)
+
+```json
+{
+  "modelContextProtocol.mcpServers": {
+    "fenix": {
+      "command": "fenix-mcp",
+      "args": ["--pat", "your-token"]
+    }
+  }
+}
+```
+
+> 💡 Install with `pipx install fenix-mcp --python python3.11` to keep the CLI isolated from your global Python.
+
+## 🌐 Optional HTTP Transport
+
+```bash
+export FENIX_TRANSPORT_MODE=http
+export FENIX_HTTP_PORT=5003
+fenix-mcp --pat <your-token>
+```
+
+Set `FENIX_TRANSPORT_MODE=both` to run STDIO and HTTP simultaneously. The default JSON-RPC endpoint is `http://127.0.0.1:5003/jsonrpc`.
+
+## 🔧 Environment Variables
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `FENIX_API_URL` | Base URL of Fênix Cloud API | `https://fenix-api.devshire.app` |
+| `FENIX_PAT_TOKEN` | Token used when `--pat` is omitted | empty |
+| `FENIX_TRANSPORT_MODE` | `stdio`, `http`, or `both` | `stdio` |
+| `FENIX_HTTP_HOST` | Host for HTTP transport | `127.0.0.1` |
+| `FENIX_HTTP_PORT` | Port for HTTP transport | `5003` |
+| `FENIX_LOG_LEVEL` | Global log level (`DEBUG`, `INFO`, …) | `INFO` |
+
+> Copy `.env.example` to `.env` for easier customization.
+
+## 🧪 Local Testing
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+## 🔄 Automation
+
+- **CI (GitHub Actions)** – runs on pushes and pull requests targeting `main`. It installs dependencies, runs `pytest`, builds the distribution artifacts, and uploads them as workflow artifacts.
+- **Publish workflow** – push a tag `v*` (or trigger the "Publish" workflow manually) to build the package and, if `PYPI_API_TOKEN` is set in repository secrets, upload artifacts to PyPI via `twine`.
+
+## 🧰 Available Tools
+
+- `knowledge` – documentation CRUD, work items, modes, rules
+- `productivity` – TODO management
+- `intelligence` – memories and smart operations
+- `initialize` – personalized setup
+- `health` – backend health check
+
+## 🔐 Security Tips
+
+- Store tokens securely (`pass`, keychain, `.env`) and never commit secrets.
+- Revoke tokens when no longer needed.
+- In shared environments, prefer `pipx + FENIX_PAT_TOKEN` exported per session.
+
+## ❓ Troubleshooting
+
+<details>
+<summary><b>"command not found: fenix-mcp"</b></summary>
+
+- Ensure the `pipx`/`pip --user` scripts directory is on your `PATH`.
+- macOS/Linux: `export PATH="$PATH:~/.local/bin"`
+- Windows: check `%APPDATA%\Python\Python311\Scripts` (adjust version as needed).
+
+</details>
+
+<details>
+<summary><b>"401 Unauthorized" or authentication errors</b></summary>
+
+- Confirm `--pat` or `FENIX_PAT_TOKEN` is set correctly.
+- Regenerate tokens in Fênix Cloud if they have expired or been revoked.
+
+</details>
+
+<details>
+<summary><b>Use HTTP and STDIO at the same time</b></summary>
+
+```bash
+export FENIX_TRANSPORT_MODE=both
+fenix-mcp --pat <your-token>
+```
+
+STDIO stays active for MCP clients; HTTP will listen on `FENIX_HTTP_HOST:FENIX_HTTP_PORT`.
+
+</details>
+
+## 🗺 Roadmap
+
+- Official Docker image for Fênix MCP
+- Convenience install scripts (`curl | sh`) for macOS/Linux/Windows
+- Additional integrations (public core documents, more tools)
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a branch: `git checkout -b feat/my-feature`
+3. Install dev dependencies: `pip install -e .[dev]`
+4. Run `pytest`
+5. Open a Pull Request describing your changes
+
+## 📄 License
+
+Distributed under the [MIT License](./LICENSE).

fenix_mcp-0.1.0/README.md

@@ -0,0 +1,192 @@
+# Fênix MCP — Live Access to Fênix Cloud Data
+
+[![PyPI](https://img.shields.io/pypi/v/fenix-mcp.svg)](https://pypi.org/project/fenix-mcp/) [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+**Fênix MCP** connects MCP-compatible clients (Codex, Cursor, Context7, Windsurf, VS Code, etc.) directly to the Fênix Cloud APIs. Every tool invocation hits the live backend—no outdated snapshots or hallucinated IDs.
+
+## ❌ Without Fênix MCP
+
+- Manual lookups in the web console slow you down
+- Agents fabricate document status, IDs, or team data
+- Automation workflows stall on stale information
+
+## ✅ With Fênix MCP
+
+- Real-time API calls over STDIO or HTTP
+- Rich toolset: documentation CRUD, work items, modes, rules, TODOs, memories
+- Built for multi-user environments and multiple MCP clients
+
+## 🛠 Requirements
+
+- Python 3.10 or newer
+- Fênix Cloud Personal Access Token (`FENIX_PAT_TOKEN`)
+- Any MCP client (Codex, Cursor, VS Code MCP, etc.)
+
+## 🚀 Installation
+
+### With `pipx` (recommended)
+
+```bash
+pipx install fenix-mcp
+```
+
+### With `pip`
+
+```bash
+pip install --user fenix-mcp
+```
+
+To upgrade:
+
+```bash
+pipx upgrade fenix-mcp
+# or
+pip install --upgrade fenix-mcp
+```
+
+## ▶️ Quick Start
+
+Launch the STDIO server by providing your token (or set `FENIX_PAT_TOKEN` beforehand):
+
+```bash
+fenix-mcp --pat <your-token>
+```
+
+The command accepts all flags supported by `fenix_mcp.main` and responds over STDIO, ready for MCP clients.
+
+## ⚙️ MCP Client Configuration
+
+### Codex CLI (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers.fenix]
+command = "fenix-mcp"
+args = ["--pat", "your-token"]
+```
+
+### Cursor (`~/.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "fenix": {
+      "command": "fenix-mcp",
+      "args": ["--pat", "your-token"],
+      "disabled": false
+    }
+  }
+}
+```
+
+### VS Code (Insiders) / Windsurf (`settings.json`)
+
+```json
+{
+  "modelContextProtocol.mcpServers": {
+    "fenix": {
+      "command": "fenix-mcp",
+      "args": ["--pat", "your-token"]
+    }
+  }
+}
+```
+
+> 💡 Install with `pipx install fenix-mcp --python python3.11` to keep the CLI isolated from your global Python.
+
+## 🌐 Optional HTTP Transport
+
+```bash
+export FENIX_TRANSPORT_MODE=http
+export FENIX_HTTP_PORT=5003
+fenix-mcp --pat <your-token>
+```
+
+Set `FENIX_TRANSPORT_MODE=both` to run STDIO and HTTP simultaneously. The default JSON-RPC endpoint is `http://127.0.0.1:5003/jsonrpc`.
+
+## 🔧 Environment Variables
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `FENIX_API_URL` | Base URL of Fênix Cloud API | `https://fenix-api.devshire.app` |
+| `FENIX_PAT_TOKEN` | Token used when `--pat` is omitted | empty |
+| `FENIX_TRANSPORT_MODE` | `stdio`, `http`, or `both` | `stdio` |
+| `FENIX_HTTP_HOST` | Host for HTTP transport | `127.0.0.1` |
+| `FENIX_HTTP_PORT` | Port for HTTP transport | `5003` |
+| `FENIX_LOG_LEVEL` | Global log level (`DEBUG`, `INFO`, …) | `INFO` |
+
+> Copy `.env.example` to `.env` for easier customization.
+
+## 🧪 Local Testing
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+## 🔄 Automation
+
+- **CI (GitHub Actions)** – runs on pushes and pull requests targeting `main`. It installs dependencies, runs `pytest`, builds the distribution artifacts, and uploads them as workflow artifacts.
+- **Publish workflow** – push a tag `v*` (or trigger the "Publish" workflow manually) to build the package and, if `PYPI_API_TOKEN` is set in repository secrets, upload artifacts to PyPI via `twine`.
+
+## 🧰 Available Tools
+
+- `knowledge` – documentation CRUD, work items, modes, rules
+- `productivity` – TODO management
+- `intelligence` – memories and smart operations
+- `initialize` – personalized setup
+- `health` – backend health check
+
+## 🔐 Security Tips
+
+- Store tokens securely (`pass`, keychain, `.env`) and never commit secrets.
+- Revoke tokens when no longer needed.
+- In shared environments, prefer `pipx + FENIX_PAT_TOKEN` exported per session.
+
+## ❓ Troubleshooting
+
+<details>
+<summary><b>"command not found: fenix-mcp"</b></summary>
+
+- Ensure the `pipx`/`pip --user` scripts directory is on your `PATH`.
+- macOS/Linux: `export PATH="$PATH:~/.local/bin"`
+- Windows: check `%APPDATA%\Python\Python311\Scripts` (adjust version as needed).
+
+</details>
+
+<details>
+<summary><b>"401 Unauthorized" or authentication errors</b></summary>
+
+- Confirm `--pat` or `FENIX_PAT_TOKEN` is set correctly.
+- Regenerate tokens in Fênix Cloud if they have expired or been revoked.
+
+</details>
+
+<details>
+<summary><b>Use HTTP and STDIO at the same time</b></summary>
+
+```bash
+export FENIX_TRANSPORT_MODE=both
+fenix-mcp --pat <your-token>
+```
+
+STDIO stays active for MCP clients; HTTP will listen on `FENIX_HTTP_HOST:FENIX_HTTP_PORT`.
+
+</details>
+
+## 🗺 Roadmap
+
+- Official Docker image for Fênix MCP
+- Convenience install scripts (`curl | sh`) for macOS/Linux/Windows
+- Additional integrations (public core documents, more tools)
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a branch: `git checkout -b feat/my-feature`
+3. Install dev dependencies: `pip install -e .[dev]`
+4. Run `pytest`
+5. Open a Pull Request describing your changes
+
+## 📄 License
+
+Distributed under the [MIT License](./LICENSE).

fenix_mcp-0.1.0/fenix_mcp/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: 2024 Bruno Fernandes
+# SPDX-License-Identifier: MIT
+
+"""
+Fênix Cloud MCP Server (Python edition).
+
+This package follows a Clean Architecture layout inside the MCP ecosystem:
+
+- interface: transports and MCP protocol glue code
+- application: tools, registries, presenters and use-case orchestrators
+- domain: pure business models and services
+- infrastructure: API clients, config, logging and shared context
+"""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

fenix_mcp-0.1.0/fenix_mcp/application/presenters.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: MIT
+"""Helpers to format MCP responses."""
+
+from __future__ import annotations
+
+from typing import Iterable, List
+
+from fenix_mcp.application.tool_base import ToolResponse
+
+
+def text(content: str) -> ToolResponse:
+    return {"content": [{"type": "text", "text": content}]}
+
+
+def bullet_list(title: str, items: Iterable[str]) -> ToolResponse:
+    body_lines: List[str] = [title, ""]
+    body_lines.extend(f"- {item}" for item in items)
+    return text("\n".join(body_lines))
+
+
+def key_value(title: str, **values: str) -> ToolResponse:
+    lines = [title, ""]
+    lines.extend(f"{key}: {value}" for key, value in values.items())
+    return text("\n".join(lines))

fenix_mcp-0.1.0/fenix_mcp/application/tool_base.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: MIT
+"""Base abstractions for MCP tools."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Type
+
+from pydantic import BaseModel, ConfigDict
+
+from fenix_mcp.infrastructure.context import AppContext
+
+
+class ToolRequest(BaseModel):
+    """Base request payload."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+ToolResponse = Dict[str, Any]
+
+
+class Tool(ABC):
+    """Interface implemented by all tools."""
+
+    name: str
+    description: str
+    request_model: Type[ToolRequest] = ToolRequest
+
+    def schema(self) -> Dict[str, Any]:
+        """Return JSON schema describing the tool arguments."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "inputSchema": self.request_model.model_json_schema(),
+        }
+
+    async def execute(self, raw_arguments: Dict[str, Any], context: AppContext) -> ToolResponse:
+        """Validate raw arguments and run the tool."""
+        payload = self.request_model.model_validate(raw_arguments or {})
+        return await self.run(payload, context)
+
+    @abstractmethod
+    async def run(self, payload: ToolRequest, context: AppContext) -> ToolResponse:
+        """Execute business logic and return a MCP-formatted response."""
+

fenix_mcp-0.1.0/fenix_mcp/application/tool_registry.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: MIT
+"""Registry that keeps the mapping between tool names and instances."""
+
+from __future__ import annotations
+
+from typing import Dict, Iterable, List
+
+from fenix_mcp.application.tool_base import Tool, ToolResponse
+from fenix_mcp.infrastructure.context import AppContext
+
+
+class ToolRegistry:
+    """Lookup table for tool execution."""
+
+    def __init__(self, tools: Iterable[Tool]):
+        self._tools: Dict[str, Tool] = {}
+        for tool in tools:
+            if tool.name in self._tools:
+                raise ValueError(f"Duplicate tool name detected: {tool.name}")
+            self._tools[tool.name] = tool
+
+    def list_definitions(self) -> List[dict]:
+        return [tool.schema() for tool in self._tools.values()]
+
+    async def execute(self, name: str, arguments: dict, context: AppContext) -> ToolResponse:
+        try:
+            tool = self._tools[name]
+        except KeyError as exc:
+            raise KeyError(f"Unknown tool '{name}'") from exc
+        return await tool.execute(arguments, context)
+
+
+def build_default_registry(context: AppContext) -> ToolRegistry:
+    from fenix_mcp.application.tools import build_tools
+
+    tools = build_tools(context)
+    return ToolRegistry(tools)

fenix_mcp-0.1.0/fenix_mcp/application/tools/__init__.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+"""Factory functions to instantiate all tools."""
+
+from __future__ import annotations
+
+from typing import List
+
+from fenix_mcp.application.tool_base import Tool
+from fenix_mcp.infrastructure.context import AppContext
+
+from .health import HealthTool
+from .initialize import InitializeTool
+from .intelligence import IntelligenceTool
+from .productivity import ProductivityTool
+from .knowledge import KnowledgeTool
+from .user_config import UserConfigTool
+
+
+def build_tools(context: AppContext) -> List[Tool]:
+    """Instantiate all available tools."""
+
+    return [
+        HealthTool(context),
+        InitializeTool(context),
+        IntelligenceTool(context),
+        ProductivityTool(context),
+        KnowledgeTool(context),
+        UserConfigTool(context),
+    ]

fenix_mcp-0.1.0/fenix_mcp/application/tools/health.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MIT
+"""Health check tool."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from fenix_mcp.application.presenters import key_value, text
+from fenix_mcp.application.tool_base import Tool, ToolRequest
+from fenix_mcp.infrastructure.context import AppContext
+
+
+class _HealthRequest(ToolRequest):
+    pass
+
+
+class HealthTool(Tool):
+    name = "fenix_health_check"
+    description = "Check if Fênix Cloud Backend is healthy and accessible."
+    request_model = _HealthRequest
+
+    def __init__(self, context: AppContext):
+        self._context = context
+
+    async def run(self, payload: ToolRequest, context: AppContext):
+        api_health = self._context.api_client.get_health() or {}
+        return key_value(
+            "Fênix Cloud Backend Health",
+            status=str(api_health.get("status", "unknown")),
+        )