Metadata-Version: 2.4
Name: allye-mcp
Version: 1.23.1
Summary: Fênix Cloud MCP server implemented in Python
Author: Allye 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
Requires-Dist: python-json-logger>=2.0
Requires-Dist: PyJWT[crypto]>=2.8
Requires-Dist: tzdata>=2024.1
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black==26.1.0; extra == "dev"
Requires-Dist: flake8==7.3.0; extra == "dev"
Requires-Dist: mypy==1.19.1; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"

<p align="center">
  <img src="https://allye.devshire.app/logos/logo_allye.png" alt="Allye MCP" width="200" />
</p>

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

<p align="center">
  <a href="https://pypi.org/project/allye-mcp/"><img src="https://img.shields.io/pypi/v/allye-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>
  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
  <a href="https://codecov.io/gh/allye-devshire/allye-mcp-py"><img src="https://codecov.io/gh/allye-devshire/allye-mcp-py/branch/main/graph/badge.svg" alt="codecov"></a>
</p>

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

---

## 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:**
- `kb` — Project knowledge base: search, read and write pages by section with revision checks, backlinks, history and restore (use it for project docs)
- `skills` — Authorized document library: create, read, edit, trash, and revision history
- `productivity` — Personal TODO management (never shared): scheduling, Today/Upcoming/Someday/Logbook views, checklists, reordering and a link to a spec
- `intelligence` — Memories and smart operations
- `user_config` — Deprecated: returns no data (use `memory_preferences`); removal planned after 30 days in production
- `initialize` — Session context (user, tenant, teams, open work); `include_user_docs` is deprecated and ignored
- `allye_health_check` — Backend health check
- `api_catalog` — Allye API specifications: search, list and inspect endpoint details
- `projects`, `epics`, `specs`, `tasks` — Projects module (Project → Epic → Spec → Task)
- `team` — Default team: `team_set_default` sets your default team (shared by all your sessions)

See [Tools](./docs/tools.md) for the skills library and the Projects module.

---

## Quick Start

### Remote server with native OAuth (recommended)

Configure the server name `allye` with the canonical URL:

```text
https://mcp.allye.app/mcp
```

Use the client's native MCP OAuth flow. Do not configure a fixed
`Authorization` header, PAT, legacy client ID, tenant path, or token helper.
The client discovers OAuth from:

```text
https://mcp.allye.app/.well-known/oauth-protected-resource/mcp
```

Examples:

```bash
# Claude Code
claude mcp add --transport http allye https://mcp.allye.app/mcp

# Codex
codex mcp add allye --url https://mcp.allye.app/mcp
codex mcp login allye
```

For OpenCode, define an enabled remote server named `allye` at the same URL,
then run `opencode mcp auth allye`. With Pi and `pi-mcp-adapter`, configure the
same name and URL, then use `/mcp-auth allye` and `/mcp reconnect allye`.
Each installation completes its own browser authorization.

### Local STDIO with an explicit PAT

PAT authentication remains supported only for local STDIO:

```bash
pipx install allye-mcp
ALLYE_TRANSPORT_MODE=stdio allye-mcp --pat <your-token>
```

---

## Documentation

| Topic | File |
|-------|------|
| Tools: skills library, Projects module | [docs/tools.md](./docs/tools.md) |
| Requirements and installation | [docs/installation.md](./docs/installation.md) |
| Configuration: STDIO, environment variables, HTTP | [docs/configuration.md](./docs/configuration.md) |
| Project structure and tech stack | [docs/project-structure.md](./docs/project-structure.md) |
| Development, commit convention, CI/CD | [docs/development.md](./docs/development.md) |
| Troubleshooting | [docs/troubleshooting.md](./docs/troubleshooting.md) |
| Security | [docs/security.md](./docs/security.md) |
| Testing | [TESTING.md](./TESTING.md) |
| MCP action → API mapping | [docs/testing/mcp_action_matrix.md](./docs/testing/mcp_action_matrix.md) |

---

## Useful Links

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