allye-mcp 1.3.0

Fênix Cloud MCP server implemented in Python

Allye MCP Server
Python MCP server for Allye Cloud API integration

Quick Start • Installation • Configuration • Structure • Testing

---

Overview

Allye MCP connects MCP-compatible clients (Claude Code, Cursor, Windsurf, VS Code, etc.) directly to the Allye 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 allye-mcp                    # Install
allye-mcp --pat <your-token>              # Run (STDIO mode)

---

Requirements

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

---

Installation

With pipx (recommended)

pipx install allye-mcp

With pip

pip install --user allye-mcp

Upgrade

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

---

Configuration

MCP Client Setup

Claude Code — ~/.claude/config.toml

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

Cursor — ~/.cursor/mcp.json

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

VS Code / Windsurf — settings.json

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

---

Environment Variables

Variable	Description	Default
ALLYE_API_URL	Allye Cloud API base URL	https://allye-api.devshire.app
ALLYE_PAT_TOKEN	Token (alternative to --pat)	empty
ALLYE_TRANSPORT_MODE	stdio, http, or both	stdio
ALLYE_HTTP_HOST	HTTP transport host	127.0.0.1
ALLYE_HTTP_PORT	HTTP transport port	5003
ALLYE_LOG_LEVEL	Log level (DEBUG, INFO, etc.)	INFO

See .env.example for reference.

HTTP Transport

export ALLYE_TRANSPORT_MODE=http
export ALLYE_HTTP_PORT=5003
allye-mcp --pat <your-token>

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

Run both STDIO and HTTP:

export ALLYE_TRANSPORT_MODE=both
allye-mcp --pat <your-token>

---

Project Structure

allye-mcp-py/
├── allye_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

allye_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/ → Allye 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 allye-mcp-py
pip install -e .[dev]

Scripts

Command	Description
pytest	Run tests
pytest --cov=allye_mcp	Run with coverage
black allye_mcp/ tests/	Format code
flake8 allye_mcp/ tests/	Lint
mypy allye_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: allye-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 ALLYE_PAT_TOKEN is set correctly
2. Regenerate token in Allye Cloud if expired

Run HTTP and STDIO simultaneously

export ALLYE_TRANSPORT_MODE=both
allye-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/allye-mcp/
Allye Cloud	https://allye.devshire.app
MCP Protocol	https://modelcontextprotocol.io