fenix-mcp 1.14.0__py3-none-any.whl → 2.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fenix_mcp/__init__.py +1 -1
- fenix_mcp/application/tools/initialize.py +18 -56
- fenix_mcp/application/tools/intelligence.py +130 -304
- fenix_mcp/application/tools/knowledge.py +342 -10
- fenix_mcp/domain/initialization.py +11 -112
- fenix_mcp/domain/intelligence.py +57 -247
- fenix_mcp/domain/knowledge.py +22 -0
- fenix_mcp/infrastructure/fenix_api/client.py +108 -23
- fenix_mcp/interface/mcp_server.py +12 -0
- fenix_mcp-2.0.0.dist-info/METADATA +341 -0
- {fenix_mcp-1.14.0.dist-info → fenix_mcp-2.0.0.dist-info}/RECORD +14 -14
- {fenix_mcp-1.14.0.dist-info → fenix_mcp-2.0.0.dist-info}/WHEEL +1 -1
- fenix_mcp-1.14.0.dist-info/METADATA +0 -258
- {fenix_mcp-1.14.0.dist-info → fenix_mcp-2.0.0.dist-info}/entry_points.txt +0 -0
- {fenix_mcp-1.14.0.dist-info → fenix_mcp-2.0.0.dist-info}/top_level.txt +0 -0
|
@@ -0,0 +1,341 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: fenix-mcp
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: Fênix Cloud MCP server implemented in Python
|
|
5
|
+
Author: Fenix Inc
|
|
6
|
+
Requires-Python: >=3.10
|
|
7
|
+
Description-Content-Type: text/markdown
|
|
8
|
+
Requires-Dist: pydantic>=2.5
|
|
9
|
+
Requires-Dist: requests>=2.31
|
|
10
|
+
Requires-Dist: urllib3>=2.0
|
|
11
|
+
Requires-Dist: aiohttp>=3.9
|
|
12
|
+
Requires-Dist: pydantic-settings>=2.0
|
|
13
|
+
Provides-Extra: dev
|
|
14
|
+
Requires-Dist: pytest>=7.4; extra == "dev"
|
|
15
|
+
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
|
|
16
|
+
Requires-Dist: pytest-cov>=4.0; extra == "dev"
|
|
17
|
+
Requires-Dist: black>=23.0; extra == "dev"
|
|
18
|
+
Requires-Dist: flake8>=6.0; extra == "dev"
|
|
19
|
+
Requires-Dist: mypy>=1.0; extra == "dev"
|
|
20
|
+
Requires-Dist: twine>=4.0; extra == "dev"
|
|
21
|
+
|
|
22
|
+
<p align="center">
|
|
23
|
+
<img src="https://fenix.devshire.app/logos/logo_fenix.png" alt="Fenix MCP" width="200" />
|
|
24
|
+
</p>
|
|
25
|
+
|
|
26
|
+
<p align="center">
|
|
27
|
+
<strong>Fenix MCP Server</strong><br/>
|
|
28
|
+
Python MCP server for Fenix Cloud API integration
|
|
29
|
+
</p>
|
|
30
|
+
|
|
31
|
+
<p align="center">
|
|
32
|
+
<a href="https://pypi.org/project/fenix-mcp/"><img src="https://img.shields.io/pypi/v/fenix-mcp.svg" alt="PyPI"></a>
|
|
33
|
+
<a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python"></a>
|
|
34
|
+
<a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"></a>
|
|
35
|
+
</p>
|
|
36
|
+
|
|
37
|
+
<p align="center">
|
|
38
|
+
<a href="#quick-start">Quick Start</a> •
|
|
39
|
+
<a href="#installation">Installation</a> •
|
|
40
|
+
<a href="#configuration">Configuration</a> •
|
|
41
|
+
<a href="#project-structure">Structure</a>
|
|
42
|
+
</p>
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Overview
|
|
47
|
+
|
|
48
|
+
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.
|
|
49
|
+
|
|
50
|
+
**Available Tools:**
|
|
51
|
+
- `knowledge` — Documentation CRUD, work items, modes, rules
|
|
52
|
+
- `productivity` — TODO management
|
|
53
|
+
- `intelligence` — Memories and smart operations
|
|
54
|
+
- `user_config` — User configuration documents
|
|
55
|
+
- `initialize` — Personalized setup
|
|
56
|
+
- `health` — Backend health check
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## Quick Start
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
pipx install fenix-mcp # Install
|
|
64
|
+
fenix-mcp --pat <your-token> # Run (STDIO mode)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## Requirements
|
|
70
|
+
|
|
71
|
+
| Requirement | Version |
|
|
72
|
+
|-------------|---------|
|
|
73
|
+
| Python | 3.10+ |
|
|
74
|
+
| Fenix PAT Token | Required |
|
|
75
|
+
| MCP Client | Claude Code, Cursor, Windsurf, VS Code, etc. |
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Installation
|
|
80
|
+
|
|
81
|
+
### With pipx (recommended)
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
pipx install fenix-mcp
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### With pip
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
pip install --user fenix-mcp
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Upgrade
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
pipx upgrade fenix-mcp
|
|
97
|
+
# or
|
|
98
|
+
pip install --upgrade fenix-mcp
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## Configuration
|
|
104
|
+
|
|
105
|
+
### MCP Client Setup
|
|
106
|
+
|
|
107
|
+
<details>
|
|
108
|
+
<summary><strong>Claude Code</strong> — ~/.claude/config.toml</summary>
|
|
109
|
+
|
|
110
|
+
```toml
|
|
111
|
+
[mcp_servers.fenix]
|
|
112
|
+
command = "fenix-mcp"
|
|
113
|
+
args = ["--pat", "your-token"]
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
</details>
|
|
117
|
+
|
|
118
|
+
<details>
|
|
119
|
+
<summary><strong>Cursor</strong> — ~/.cursor/mcp.json</summary>
|
|
120
|
+
|
|
121
|
+
```json
|
|
122
|
+
{
|
|
123
|
+
"mcpServers": {
|
|
124
|
+
"fenix": {
|
|
125
|
+
"command": "fenix-mcp",
|
|
126
|
+
"args": ["--pat", "your-token"],
|
|
127
|
+
"disabled": false
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
</details>
|
|
134
|
+
|
|
135
|
+
<details>
|
|
136
|
+
<summary><strong>VS Code / Windsurf</strong> — settings.json</summary>
|
|
137
|
+
|
|
138
|
+
```json
|
|
139
|
+
{
|
|
140
|
+
"modelContextProtocol.mcpServers": {
|
|
141
|
+
"fenix": {
|
|
142
|
+
"command": "fenix-mcp",
|
|
143
|
+
"args": ["--pat", "your-token"]
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
</details>
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
<details>
|
|
154
|
+
<summary><strong>Environment Variables</strong></summary>
|
|
155
|
+
|
|
156
|
+
| Variable | Description | Default |
|
|
157
|
+
|----------|-------------|---------|
|
|
158
|
+
| `FENIX_API_URL` | Fenix Cloud API base URL | `https://fenix-api.devshire.app` |
|
|
159
|
+
| `FENIX_PAT_TOKEN` | Token (alternative to `--pat`) | empty |
|
|
160
|
+
| `FENIX_TRANSPORT_MODE` | `stdio`, `http`, or `both` | `stdio` |
|
|
161
|
+
| `FENIX_HTTP_HOST` | HTTP transport host | `127.0.0.1` |
|
|
162
|
+
| `FENIX_HTTP_PORT` | HTTP transport port | `5003` |
|
|
163
|
+
| `FENIX_LOG_LEVEL` | Log level (`DEBUG`, `INFO`, etc.) | `INFO` |
|
|
164
|
+
|
|
165
|
+
See [`.env.example`](./.env.example) for reference.
|
|
166
|
+
|
|
167
|
+
</details>
|
|
168
|
+
|
|
169
|
+
<details>
|
|
170
|
+
<summary><strong>HTTP Transport</strong></summary>
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
export FENIX_TRANSPORT_MODE=http
|
|
174
|
+
export FENIX_HTTP_PORT=5003
|
|
175
|
+
fenix-mcp --pat <your-token>
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
JSON-RPC endpoint: `http://127.0.0.1:5003/jsonrpc`
|
|
179
|
+
|
|
180
|
+
Run both STDIO and HTTP:
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
export FENIX_TRANSPORT_MODE=both
|
|
184
|
+
fenix-mcp --pat <your-token>
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
</details>
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## Project Structure
|
|
192
|
+
|
|
193
|
+
```
|
|
194
|
+
fenix-mcp-py/
|
|
195
|
+
├── fenix_mcp/ # Main package
|
|
196
|
+
│ ├── main.py # Entry point (CLI)
|
|
197
|
+
│ ├── application/ # Use cases and services
|
|
198
|
+
│ ├── domain/ # Business entities
|
|
199
|
+
│ ├── infrastructure/ # External integrations (API, transport)
|
|
200
|
+
│ └── interface/ # MCP protocol handlers
|
|
201
|
+
├── tests/ # Test suite
|
|
202
|
+
├── docs/ # Documentation
|
|
203
|
+
├── pyproject.toml # Project configuration
|
|
204
|
+
└── .env.example # Environment template
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
<details>
|
|
208
|
+
<summary><strong>fenix_mcp/</strong> — Package Structure</summary>
|
|
209
|
+
|
|
210
|
+
| Directory | Responsibility |
|
|
211
|
+
|-----------|----------------|
|
|
212
|
+
| `main.py` | CLI entry point, argument parsing, server bootstrap |
|
|
213
|
+
| `application/` | Use cases, handlers for each MCP tool |
|
|
214
|
+
| `domain/` | Business entities, DTOs, validation |
|
|
215
|
+
| `infrastructure/` | API client, HTTP transport, logging |
|
|
216
|
+
| `interface/` | MCP protocol implementation, tool registration |
|
|
217
|
+
|
|
218
|
+
### Architecture
|
|
219
|
+
|
|
220
|
+
```
|
|
221
|
+
MCP Client → interface/ → application/ → infrastructure/ → Fenix API
|
|
222
|
+
↓
|
|
223
|
+
domain/
|
|
224
|
+
(entities)
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
</details>
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## Tech Stack
|
|
232
|
+
|
|
233
|
+
| Layer | Technology |
|
|
234
|
+
|-------|------------|
|
|
235
|
+
| Runtime | Python 3.10+ |
|
|
236
|
+
| Validation | Pydantic 2 |
|
|
237
|
+
| HTTP | aiohttp, requests |
|
|
238
|
+
| Config | pydantic-settings |
|
|
239
|
+
| Testing | pytest, pytest-asyncio |
|
|
240
|
+
| Linting | flake8, black, mypy |
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
## Development
|
|
245
|
+
|
|
246
|
+
### Setup
|
|
247
|
+
|
|
248
|
+
```bash
|
|
249
|
+
# Clone and install
|
|
250
|
+
git clone <repo>
|
|
251
|
+
cd fenix-mcp-py
|
|
252
|
+
pip install -e .[dev]
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
### Scripts
|
|
256
|
+
|
|
257
|
+
| Command | Description |
|
|
258
|
+
|---------|-------------|
|
|
259
|
+
| `pytest` | Run tests |
|
|
260
|
+
| `pytest --cov=fenix_mcp` | Run with coverage |
|
|
261
|
+
| `black fenix_mcp/ tests/` | Format code |
|
|
262
|
+
| `flake8 fenix_mcp/ tests/` | Lint |
|
|
263
|
+
| `mypy fenix_mcp/` | Type check |
|
|
264
|
+
|
|
265
|
+
### Commit Convention
|
|
266
|
+
|
|
267
|
+
Follow [Conventional Commits](https://www.conventionalcommits.org/):
|
|
268
|
+
|
|
269
|
+
| Prefix | Description | Version Bump |
|
|
270
|
+
|--------|-------------|--------------|
|
|
271
|
+
| `fix:` | Bug fixes | Patch |
|
|
272
|
+
| `feat:` | New features | Minor |
|
|
273
|
+
| `BREAKING CHANGE:` | Breaking changes | Major |
|
|
274
|
+
| `chore:` | Maintenance | None |
|
|
275
|
+
| `docs:` | Documentation | None |
|
|
276
|
+
|
|
277
|
+
---
|
|
278
|
+
|
|
279
|
+
## CI/CD
|
|
280
|
+
|
|
281
|
+
| Platform | Usage |
|
|
282
|
+
|----------|-------|
|
|
283
|
+
| GitHub Actions | Tests, lint, build on push/PR to main |
|
|
284
|
+
| Semantic Release | Auto-version based on commits |
|
|
285
|
+
| PyPI | Package distribution |
|
|
286
|
+
|
|
287
|
+
---
|
|
288
|
+
|
|
289
|
+
## Troubleshooting
|
|
290
|
+
|
|
291
|
+
<details>
|
|
292
|
+
<summary><code>command not found: fenix-mcp</code></summary>
|
|
293
|
+
|
|
294
|
+
Add scripts directory to PATH:
|
|
295
|
+
|
|
296
|
+
```bash
|
|
297
|
+
# macOS/Linux
|
|
298
|
+
export PATH="$PATH:~/.local/bin"
|
|
299
|
+
|
|
300
|
+
# Windows
|
|
301
|
+
# Add %APPDATA%\Python\Python311\Scripts to PATH
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
</details>
|
|
305
|
+
|
|
306
|
+
<details>
|
|
307
|
+
<summary><code>401 Unauthorized</code></summary>
|
|
308
|
+
|
|
309
|
+
1. Check `--pat` or `FENIX_PAT_TOKEN` is set correctly
|
|
310
|
+
2. Regenerate token in Fenix Cloud if expired
|
|
311
|
+
|
|
312
|
+
</details>
|
|
313
|
+
|
|
314
|
+
<details>
|
|
315
|
+
<summary>Run HTTP and STDIO simultaneously</summary>
|
|
316
|
+
|
|
317
|
+
```bash
|
|
318
|
+
export FENIX_TRANSPORT_MODE=both
|
|
319
|
+
fenix-mcp --pat <your-token>
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
</details>
|
|
323
|
+
|
|
324
|
+
---
|
|
325
|
+
|
|
326
|
+
## Security
|
|
327
|
+
|
|
328
|
+
- Store tokens securely (keychain, `pass`, `.env`)
|
|
329
|
+
- Never commit secrets to git
|
|
330
|
+
- Revoke tokens when no longer needed
|
|
331
|
+
- Use `pipx` to isolate from global Python
|
|
332
|
+
|
|
333
|
+
---
|
|
334
|
+
|
|
335
|
+
## Useful Links
|
|
336
|
+
|
|
337
|
+
| Resource | URL |
|
|
338
|
+
|----------|-----|
|
|
339
|
+
| PyPI | https://pypi.org/project/fenix-mcp/ |
|
|
340
|
+
| Fenix Cloud | https://fenix.devshire.app |
|
|
341
|
+
| MCP Protocol | https://modelcontextprotocol.io |
|
|
@@ -1,18 +1,18 @@
|
|
|
1
|
-
fenix_mcp/__init__.py,sha256=
|
|
1
|
+
fenix_mcp/__init__.py,sha256=ewwBzUPQxM4BTmesnfhTvSBnnkCQQPE4nOkAVo-lKYM,180
|
|
2
2
|
fenix_mcp/main.py,sha256=iJV-9btNMDJMObvcn7wBQdbLLKjkYCQ1ANGEwHGHlMU,2857
|
|
3
3
|
fenix_mcp/application/presenters.py,sha256=fGME54PdCDhTBhXO-JUB9yLdBHiE1aeXLTC2fCuxnxM,689
|
|
4
4
|
fenix_mcp/application/tool_base.py,sha256=ZCb9g4ij5Hbb0410NEZTYXvPWq-Zkg8ZCsinTa3gCY4,4741
|
|
5
5
|
fenix_mcp/application/tool_registry.py,sha256=bPT5g8GfxG_qu28R1WaDOZHvtmG6TPDvZi8eWj1T9xE,1250
|
|
6
6
|
fenix_mcp/application/tools/__init__.py,sha256=Gi1YvYh-KdL9HD8gLVrknHrxiKKEOhHBEZ02KBXJaKQ,796
|
|
7
7
|
fenix_mcp/application/tools/health.py,sha256=m5DxhoRbdwl6INzd6PISxv1NAv-ljCrezsr773VB0wE,834
|
|
8
|
-
fenix_mcp/application/tools/initialize.py,sha256=
|
|
9
|
-
fenix_mcp/application/tools/intelligence.py,sha256=
|
|
10
|
-
fenix_mcp/application/tools/knowledge.py,sha256=
|
|
8
|
+
fenix_mcp/application/tools/initialize.py,sha256=YQpZ0K6uz_LiLdE_GdQ0uJKtj6cgFru38xwoaCl5Jmg,5146
|
|
9
|
+
fenix_mcp/application/tools/intelligence.py,sha256=CLw6vxeuu9NwNIINBUUCn3g5JQ2nJmSUogbTwsDhrvE,8440
|
|
10
|
+
fenix_mcp/application/tools/knowledge.py,sha256=NHr2zoTNIE1994iBABwuNARv78XToWMiZdlI4bY5ocU,70327
|
|
11
11
|
fenix_mcp/application/tools/productivity.py,sha256=Wmefwg6yuXkHwwQT999d9D4lQf0UY_jnCTDlBe2YRTg,11273
|
|
12
12
|
fenix_mcp/application/tools/user_config.py,sha256=O5AVg7IUKL9uIoUoBSFovBDHl9jofhKWzhFK7CnKi4s,6470
|
|
13
|
-
fenix_mcp/domain/initialization.py,sha256=
|
|
14
|
-
fenix_mcp/domain/intelligence.py,sha256=
|
|
15
|
-
fenix_mcp/domain/knowledge.py,sha256
|
|
13
|
+
fenix_mcp/domain/initialization.py,sha256=j7D0TsvtLqTZLmwFkrZnv1e2ZnDCuDQ_P3c8jMm2ifI,2849
|
|
14
|
+
fenix_mcp/domain/intelligence.py,sha256=khoNPqhQMZkTOvSRbLtbp7xYpYgkP57s571TnRs4WYU,2747
|
|
15
|
+
fenix_mcp/domain/knowledge.py,sha256=-4c4AyRKE-n_RmlrkCkHSnpQquZBEDNv_tiDrUtACkQ,19249
|
|
16
16
|
fenix_mcp/domain/productivity.py,sha256=PzY664eRPuBCfZGUY_Uv1GNeyMWsw6xqC54C-nobQns,6799
|
|
17
17
|
fenix_mcp/domain/user_config.py,sha256=8rzhJCNqIArfaCoKxxQXFoemCU7qww3hq0RDanIf_2Y,2028
|
|
18
18
|
fenix_mcp/infrastructure/config.py,sha256=zhJ3hhsP-bRfICcdq8rIDh5NGDe_u7AGpcgjcc2U1nY,1908
|
|
@@ -20,11 +20,11 @@ fenix_mcp/infrastructure/context.py,sha256=kiDiamiPbHZpTGyZMylcQwtLhfaDXrxAkWSst
|
|
|
20
20
|
fenix_mcp/infrastructure/http_client.py,sha256=uJwt_iBGSFa1XPFBeqtm7eznkEm8aZ1v2DSxYjloAQs,2753
|
|
21
21
|
fenix_mcp/infrastructure/logging.py,sha256=bHrWlSi_0HshRe3--BK_5nzUszW-gh37q6jsd0ShS2Y,1371
|
|
22
22
|
fenix_mcp/infrastructure/request_context.py,sha256=hAHXHh-SKizBN7-YgdaRv0JsRYXBdurO2sr9btHPjKI,1101
|
|
23
|
-
fenix_mcp/infrastructure/fenix_api/client.py,sha256=
|
|
24
|
-
fenix_mcp/interface/mcp_server.py,sha256=
|
|
23
|
+
fenix_mcp/infrastructure/fenix_api/client.py,sha256=fkXIzo2_Qs4AfnkPX8Z1k-3dwTTJ5wEG-MBCfUZ8Axo,29119
|
|
24
|
+
fenix_mcp/interface/mcp_server.py,sha256=xSIMZwOaEwHLJ1BKy_agdMiep7HFhIgsUhOVz49DsyA,2728
|
|
25
25
|
fenix_mcp/interface/transports.py,sha256=2zJtc-L73zasyiwQoZbvFJ0yT1bggL5WAa7Nm7zID3k,8502
|
|
26
|
-
fenix_mcp-
|
|
27
|
-
fenix_mcp-
|
|
28
|
-
fenix_mcp-
|
|
29
|
-
fenix_mcp-
|
|
30
|
-
fenix_mcp-
|
|
26
|
+
fenix_mcp-2.0.0.dist-info/METADATA,sha256=6oZbIkzpboBC9i1IzXjedPEo_mSECyo_9tbZ36oHQFA,7714
|
|
27
|
+
fenix_mcp-2.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
|
|
28
|
+
fenix_mcp-2.0.0.dist-info/entry_points.txt,sha256=o52x_YHBupEd-1Z1GSfUjv3gJrx5_I-EkHhCgt1WBaE,49
|
|
29
|
+
fenix_mcp-2.0.0.dist-info/top_level.txt,sha256=2G1UtKpwjaIGQyE7sRoHecxaGLeuexfjrOUjv9DDKh4,10
|
|
30
|
+
fenix_mcp-2.0.0.dist-info/RECORD,,
|
|
@@ -1,258 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: fenix-mcp
|
|
3
|
-
Version: 1.14.0
|
|
4
|
-
Summary: Fênix Cloud MCP server implemented in Python
|
|
5
|
-
Author: Fenix Inc
|
|
6
|
-
Requires-Python: >=3.10
|
|
7
|
-
Description-Content-Type: text/markdown
|
|
8
|
-
Requires-Dist: pydantic>=2.5
|
|
9
|
-
Requires-Dist: requests>=2.31
|
|
10
|
-
Requires-Dist: urllib3>=2.0
|
|
11
|
-
Requires-Dist: aiohttp>=3.9
|
|
12
|
-
Requires-Dist: pydantic-settings>=2.0
|
|
13
|
-
Provides-Extra: dev
|
|
14
|
-
Requires-Dist: pytest>=7.4; extra == "dev"
|
|
15
|
-
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
|
|
16
|
-
Requires-Dist: pytest-cov>=4.0; extra == "dev"
|
|
17
|
-
Requires-Dist: black>=23.0; extra == "dev"
|
|
18
|
-
Requires-Dist: flake8>=6.0; extra == "dev"
|
|
19
|
-
Requires-Dist: mypy>=1.0; extra == "dev"
|
|
20
|
-
Requires-Dist: twine>=4.0; extra == "dev"
|
|
21
|
-
|
|
22
|
-
# Fênix MCP — Live Access to Fênix Cloud Data
|
|
23
|
-
|
|
24
|
-
[](https://pypi.org/project/fenix-mcp/) [](https://www.python.org/) [](./LICENSE)
|
|
25
|
-
|
|
26
|
-
**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.
|
|
27
|
-
|
|
28
|
-
## ❌ Without Fênix MCP
|
|
29
|
-
|
|
30
|
-
- Manual lookups in the web console slow you down
|
|
31
|
-
- Agents fabricate document status, IDs, or team data
|
|
32
|
-
- Automation workflows stall on stale information
|
|
33
|
-
|
|
34
|
-
## ✅ With Fênix MCP
|
|
35
|
-
|
|
36
|
-
- Real-time API calls over STDIO or HTTP
|
|
37
|
-
- Rich toolset: documentation CRUD, work items, modes, rules, TODOs, memories
|
|
38
|
-
- Built for multi-user environments and multiple MCP clients
|
|
39
|
-
|
|
40
|
-
## 🛠 Requirements
|
|
41
|
-
|
|
42
|
-
- Python 3.10 or newer
|
|
43
|
-
- Fênix Cloud Personal Access Token (`FENIX_PAT_TOKEN`)
|
|
44
|
-
- Any MCP client (Codex, Cursor, VS Code MCP, etc.)
|
|
45
|
-
|
|
46
|
-
## 🚀 Installation
|
|
47
|
-
|
|
48
|
-
### With `pipx` (recommended)
|
|
49
|
-
|
|
50
|
-
```bash
|
|
51
|
-
pipx install fenix-mcp
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
### With `pip`
|
|
55
|
-
|
|
56
|
-
```bash
|
|
57
|
-
pip install --user fenix-mcp
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
To upgrade:
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
pipx upgrade fenix-mcp
|
|
64
|
-
# or
|
|
65
|
-
pip install --upgrade fenix-mcp
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
## ▶️ Quick Start
|
|
69
|
-
|
|
70
|
-
Launch the STDIO server by providing your token (or set `FENIX_PAT_TOKEN` beforehand):
|
|
71
|
-
|
|
72
|
-
```bash
|
|
73
|
-
fenix-mcp --pat <your-token>
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
The command accepts all flags supported by `fenix_mcp.main` and responds over STDIO, ready for MCP clients.
|
|
77
|
-
|
|
78
|
-
## ⚙️ MCP Client Configuration
|
|
79
|
-
|
|
80
|
-
### Codex CLI (`~/.codex/config.toml`)
|
|
81
|
-
|
|
82
|
-
```toml
|
|
83
|
-
[mcp_servers.fenix]
|
|
84
|
-
command = "fenix-mcp"
|
|
85
|
-
args = ["--pat", "your-token"]
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
### Cursor (`~/.cursor/mcp.json`)
|
|
89
|
-
|
|
90
|
-
```json
|
|
91
|
-
{
|
|
92
|
-
"mcpServers": {
|
|
93
|
-
"fenix": {
|
|
94
|
-
"command": "fenix-mcp",
|
|
95
|
-
"args": ["--pat", "your-token"],
|
|
96
|
-
"disabled": false
|
|
97
|
-
}
|
|
98
|
-
}
|
|
99
|
-
}
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
### VS Code (Insiders) / Windsurf (`settings.json`)
|
|
103
|
-
|
|
104
|
-
```json
|
|
105
|
-
{
|
|
106
|
-
"modelContextProtocol.mcpServers": {
|
|
107
|
-
"fenix": {
|
|
108
|
-
"command": "fenix-mcp",
|
|
109
|
-
"args": ["--pat", "your-token"]
|
|
110
|
-
}
|
|
111
|
-
}
|
|
112
|
-
}
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
> 💡 Install with `pipx install fenix-mcp --python python3.11` to keep the CLI isolated from your global Python.
|
|
116
|
-
|
|
117
|
-
## 🌐 Optional HTTP Transport
|
|
118
|
-
|
|
119
|
-
```bash
|
|
120
|
-
export FENIX_TRANSPORT_MODE=http
|
|
121
|
-
export FENIX_HTTP_PORT=5003
|
|
122
|
-
fenix-mcp --pat <your-token>
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
Set `FENIX_TRANSPORT_MODE=both` to run STDIO and HTTP simultaneously. The default JSON-RPC endpoint is `http://127.0.0.1:5003/jsonrpc`.
|
|
126
|
-
|
|
127
|
-
## 🔧 Environment Variables
|
|
128
|
-
|
|
129
|
-
| Variable | Description | Default |
|
|
130
|
-
| --- | --- | --- |
|
|
131
|
-
| `FENIX_API_URL` | Base URL of Fênix Cloud API | `https://fenix-api.devshire.app` |
|
|
132
|
-
| `FENIX_PAT_TOKEN` | Token used when `--pat` is omitted | empty |
|
|
133
|
-
| `FENIX_TRANSPORT_MODE` | `stdio`, `http`, or `both` | `stdio` |
|
|
134
|
-
| `FENIX_HTTP_HOST` | Host for HTTP transport | `127.0.0.1` |
|
|
135
|
-
| `FENIX_HTTP_PORT` | Port for HTTP transport | `5003` |
|
|
136
|
-
| `FENIX_LOG_LEVEL` | Global log level (`DEBUG`, `INFO`, …) | `INFO` |
|
|
137
|
-
|
|
138
|
-
> Copy `.env.example` to `.env` for easier customization.
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
## 🧪 Development
|
|
142
|
-
|
|
143
|
-
### Local Testing
|
|
144
|
-
|
|
145
|
-
```bash
|
|
146
|
-
# Install development dependencies
|
|
147
|
-
pip install -e .[dev]
|
|
148
|
-
|
|
149
|
-
# Run tests
|
|
150
|
-
pytest
|
|
151
|
-
|
|
152
|
-
# Run with coverage
|
|
153
|
-
pytest --cov=fenix_mcp --cov-report=html
|
|
154
|
-
|
|
155
|
-
# Run linting
|
|
156
|
-
flake8 fenix_mcp/ tests/
|
|
157
|
-
black --check fenix_mcp/ tests/
|
|
158
|
-
|
|
159
|
-
# Run type checking
|
|
160
|
-
mypy fenix_mcp/
|
|
161
|
-
|
|
162
|
-
# Format code
|
|
163
|
-
black fenix_mcp/ tests/
|
|
164
|
-
```
|
|
165
|
-
|
|
166
|
-
### Pre-commit Hooks (Optional)
|
|
167
|
-
|
|
168
|
-
```bash
|
|
169
|
-
# Install pre-commit
|
|
170
|
-
pip install pre-commit
|
|
171
|
-
|
|
172
|
-
# Install hooks
|
|
173
|
-
pre-commit install
|
|
174
|
-
|
|
175
|
-
# Run on all files
|
|
176
|
-
pre-commit run --all-files
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
### Commit Convention
|
|
180
|
-
|
|
181
|
-
This project follows [Conventional Commits](https://www.conventionalcommits.org/):
|
|
182
|
-
|
|
183
|
-
- `fix:` - Bug fixes (patch version bump)
|
|
184
|
-
- `feat:` - New features (minor version bump)
|
|
185
|
-
- `BREAKING CHANGE:` - Breaking changes (major version bump)
|
|
186
|
-
- `chore:` - Maintenance tasks
|
|
187
|
-
- `docs:` - Documentation changes
|
|
188
|
-
- `test:` - Test additions/changes
|
|
189
|
-
|
|
190
|
-
## 🔄 Automation
|
|
191
|
-
|
|
192
|
-
- **CI (GitHub Actions)** – runs on pushes and pull requests targeting `main`. It installs dependencies, runs tests on Python 3.11, enforces flake8/black/mypy, generates coverage, builds the distribution (`python -m build`) and, on pushes, uploads artifacts for debugging.
|
|
193
|
-
|
|
194
|
-
- **Semantic Release** – after the CI job succeeds on `main`, the workflow installs the required `semantic-release` plugins and runs `npx semantic-release`. Conventional Commits decide the next version, `scripts/bump_version.py` updates `fenix_mcp.__version__`, the build artifacts are regenerated, and release notes/assets are published to GitHub and PyPI (using `PYPI_API_TOKEN`). If no eligible commit (`feat`, `fix`, or `BREAKING CHANGE`) exists since the last tag, no new release is produced.
|
|
195
|
-
|
|
196
|
-
## 🧰 Available Tools
|
|
197
|
-
|
|
198
|
-
- `knowledge` – documentation CRUD, work items, modes, rules
|
|
199
|
-
- `productivity` – TODO management
|
|
200
|
-
- `intelligence` – memories and smart operations
|
|
201
|
-
- `initialize` – personalized setup
|
|
202
|
-
- `health` – backend health check
|
|
203
|
-
|
|
204
|
-
## 🔐 Security Tips
|
|
205
|
-
|
|
206
|
-
- Store tokens securely (`pass`, keychain, `.env`) and never commit secrets.
|
|
207
|
-
- Revoke tokens when no longer needed.
|
|
208
|
-
- In shared environments, prefer `pipx + FENIX_PAT_TOKEN` exported per session.
|
|
209
|
-
|
|
210
|
-
## ❓ Troubleshooting
|
|
211
|
-
|
|
212
|
-
<details>
|
|
213
|
-
<summary><b>"command not found: fenix-mcp"</b></summary>
|
|
214
|
-
|
|
215
|
-
- Ensure the `pipx`/`pip --user` scripts directory is on your `PATH`.
|
|
216
|
-
- macOS/Linux: `export PATH="$PATH:~/.local/bin"`
|
|
217
|
-
- Windows: check `%APPDATA%\Python\Python311\Scripts` (adjust version as needed).
|
|
218
|
-
|
|
219
|
-
</details>
|
|
220
|
-
|
|
221
|
-
<details>
|
|
222
|
-
<summary><b>"401 Unauthorized" or authentication errors</b></summary>
|
|
223
|
-
|
|
224
|
-
- Confirm `--pat` or `FENIX_PAT_TOKEN` is set correctly.
|
|
225
|
-
- Regenerate tokens in Fênix Cloud if they have expired or been revoked.
|
|
226
|
-
|
|
227
|
-
</details>
|
|
228
|
-
|
|
229
|
-
<details>
|
|
230
|
-
<summary><b>Use HTTP and STDIO at the same time</b></summary>
|
|
231
|
-
|
|
232
|
-
```bash
|
|
233
|
-
export FENIX_TRANSPORT_MODE=both
|
|
234
|
-
fenix-mcp --pat <your-token>
|
|
235
|
-
```
|
|
236
|
-
|
|
237
|
-
STDIO stays active for MCP clients; HTTP will listen on `FENIX_HTTP_HOST:FENIX_HTTP_PORT`.
|
|
238
|
-
|
|
239
|
-
</details>
|
|
240
|
-
|
|
241
|
-
## 🗺 Roadmap
|
|
242
|
-
|
|
243
|
-
- Official Docker image for Fênix MCP
|
|
244
|
-
- Convenience install scripts (`curl | sh`) for macOS/Linux/Windows
|
|
245
|
-
- Additional integrations (public core documents, more tools)
|
|
246
|
-
|
|
247
|
-
## 🤝 Contributing
|
|
248
|
-
|
|
249
|
-
1. Fork the repository
|
|
250
|
-
2. Create a branch: `git checkout -b feat/my-feature`
|
|
251
|
-
3. Install dev dependencies: `pip install -e .[dev]`
|
|
252
|
-
4. Use Conventional Commits (`feat:`, `fix:`, or `BREAKING CHANGE:`) so Semantic Release can infer the next version.
|
|
253
|
-
5. Run `pytest`
|
|
254
|
-
6. Open a Pull Request describing your changes
|
|
255
|
-
|
|
256
|
-
## 📄 License
|
|
257
|
-
|
|
258
|
-
Distributed under the [MIT License](./LICENSE).
|
|
File without changes
|
|
File without changes
|