deapi-mcp 0.7.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.
@@ -0,0 +1,642 @@
1
+ Metadata-Version: 2.5
2
+ Name: deapi-mcp
3
+ Version: 0.7.0
4
+ Summary: Production-ready MCP server for the deAPI REST API
5
+ Project-URL: Homepage, https://deapi.ai
6
+ Project-URL: Documentation, https://docs.deapi.ai/execution-modes-and-integrations/mcp-server
7
+ Project-URL: Repository, https://github.com/deapi-ai/mcp-server-deapi
8
+ Project-URL: Issues, https://github.com/deapi-ai/mcp-server-deapi/issues
9
+ Project-URL: Changelog, https://github.com/deapi-ai/mcp-server-deapi/blob/main/CHANGELOG.md
10
+ Author: deAPI Team
11
+ License-Expression: MIT
12
+ License-File: LICENSE
13
+ Keywords: agents,ai,deapi,inference,llm,mcp,model-context-protocol
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
24
+ Classifier: Typing :: Typed
25
+ Requires-Python: >=3.11
26
+ Requires-Dist: cryptography>=42.0.0
27
+ Requires-Dist: deapi-sdk<0.7,>=0.6.1
28
+ Requires-Dist: fastmcp<5,>=4.0.4
29
+ Requires-Dist: httpx>=0.27.0
30
+ Requires-Dist: pydantic-settings>=2.0.0
31
+ Requires-Dist: pydantic>=2.0.0
32
+ Requires-Dist: pyjwt>=2.8.0
33
+ Requires-Dist: python-dotenv>=1.0.0
34
+ Requires-Dist: redis<8,>=5.2
35
+ Requires-Dist: sse-starlette<4,>=3.5.0
36
+ Requires-Dist: uvicorn>=0.30.0
37
+ Provides-Extra: dev
38
+ Requires-Dist: black>=24.0.0; extra == 'dev'
39
+ Requires-Dist: fakeredis[lua]>=2.26; extra == 'dev'
40
+ Requires-Dist: mypy>=1.5; extra == 'dev'
41
+ Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
42
+ Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
43
+ Requires-Dist: pytest>=8.0.0; extra == 'dev'
44
+ Requires-Dist: ruff>=0.3.0; extra == 'dev'
45
+ Description-Content-Type: text/markdown
46
+
47
+ # deAPI MCP Server
48
+
49
+ Production-ready Model Context Protocol (MCP) server for the [deAPI](https://deapi.ai) REST API. This server exposes all deAPI AI capabilities as MCP tools, enabling LLMs to perform audio transcription, image generation, OCR, video generation, text-to-speech, and more.
50
+
51
+ > **deAPI v2** — this server targets the deAPI v2 client API (OpenAI-aligned noun paths under `/api/v2/*`). API v1 is not supported: the tools send v2 payloads only.
52
+
53
+ ## Features
54
+
55
+ - **Complete API Coverage**: 39 deAPI tools exposed via MCP, covering every v2 client endpoint
56
+ - **Smart Adaptive Polling**: Automatically polls async jobs with optimized intervals based on job type
57
+ - **OAuth 2.0 Authentication**: Secure token exchange via OAuth Authorization Code flow with PKCE
58
+ - **Error Recovery**: Automatic retry logic with exponential backoff
59
+ - **Progress Reporting**: Real-time progress updates to MCP clients
60
+ - **Type Safety**: Full Pydantic schema validation
61
+ - **Production Ready**: Built with FastMCP framework for reliability
62
+
63
+ ## Available Tools
64
+
65
+ ### Audio Tools
66
+ - `audio_transcription` - Transcribe audio files to text using Whisper models
67
+ - `audio_transcription_price` - Calculate transcription cost
68
+ - `text_to_audio` - Convert text to natural speech (TTS)
69
+ - `text_to_audio_price` - Calculate TTS cost
70
+ - `text_to_music` - Generate music from text description and lyrics
71
+ - `text_to_music_price` - Calculate music generation cost
72
+ - `audio_url_transcription` - Transcribe audio from URLs of completed Twitter Spaces
73
+ - `audio_url_transcription_price` - Calculate Twitter Spaces transcription cost
74
+
75
+ ### Video Transcription Tools
76
+ - `video_file_transcription` - Transcribe video files to text
77
+ - `video_file_transcription_price` - Calculate video file transcription cost
78
+ - `video_url_transcription` - Transcribe videos from URLs (YouTube, Twitter/X, Twitch, Kick, TikTok)
79
+ - `video_url_transcription_price` - Calculate video URL transcription cost
80
+
81
+ ### Image Tools
82
+ - `text_to_image` - Generate images from text prompts
83
+ - `image_to_image` - Transform images with text guidance
84
+ - `image_to_text` - Extract text from images (OCR)
85
+ - `image_remove_background` - Remove background from images
86
+ - `image_upscale` - Upscale images to higher resolution
87
+ - `text_to_image_price` - Calculate image generation cost
88
+ - `image_to_image_price` - Calculate image transformation cost
89
+ - `image_to_text_price` - Calculate OCR cost
90
+ - `image_remove_background_price` - Calculate background removal cost
91
+ - `image_upscale_price` - Calculate upscaling cost
92
+
93
+ ### Video Tools
94
+ - `text_to_video` - Generate videos from text prompts
95
+ - `image_to_video` - Animate static images into videos
96
+ - `audio_to_video` - Generate video conditioned on audio content
97
+ - `video_description` - Describe a video in text (from an uploaded file or a video URL)
98
+ - `video_upscale` - Upscale a video to higher resolution
99
+ - `text_to_video_price` - Calculate text-to-video cost
100
+ - `image_to_video_price` - Calculate image-to-video cost
101
+ - `audio_to_video_price` - Calculate audio-to-video cost
102
+ - `video_description_price` - Calculate video description cost
103
+ - `video_upscale_price` - Calculate video upscaling cost
104
+
105
+ ### Embedding Tools
106
+ - `text_to_embedding` - Generate text embeddings for semantic search
107
+ - `text_to_embedding_price` - Calculate embedding cost
108
+
109
+ ### Prompt Tools
110
+ - `prompt_booster` - Enhance a prompt for any deAPI inference type using AI guides (synchronous, returns refined prompt directly)
111
+ - `prompt_booster_price` - Calculate prompt-enhancement cost
112
+
113
+ ### Utility Tools
114
+ - `get_balance` - Check account balance
115
+ - `get_available_models` - List available AI models with specifications
116
+ - `check_job_status` - Query async job status by ID; with `wait_seconds` it waits for the job and returns the finished result in the original tool's shape. A failed job reports `success: false` with `error_reason`, `error_code`, `retryable` and `refunded`
117
+
118
+ ### Webhooks
119
+
120
+ Every generation tool accepts `webhook_url` (HTTPS) and an optional `webhook_secret` (32–255 chars). deAPI calls that URL when the job finishes, signed with `X-DeAPI-Signature: sha256=<HMAC-SHA256(secret, "<timestamp>.<body>")>`; the tool still returns the result to the caller as usual.
121
+
122
+ ### Model-driven defaults
123
+
124
+ Generation parameters such as `width`, `height`, `steps`, `frames` and `fps` default to the selected model's own values when left unset — each model has different limits, so there is no fixed default that works everywhere. The `get_available_models` output and every tool description list each model's accepted ranges. Set `enhance_prompt: true` on `text_to_image`/`image_to_image` to let deAPI rewrite the prompt; the result then includes `prompt_boost` with the prompt actually used.
125
+
126
+ ## Installation
127
+
128
+ ### Prerequisites
129
+
130
+ **For running the MCP server:**
131
+ - Python 3.11 or higher
132
+ - `uv`, `pip`, or `conda` for package management
133
+
134
+ **For a deAPI account:**
135
+ - Sign up at [app.deapi.ai](https://app.deapi.ai/register) and create an API token at
136
+ [app.deapi.ai/settings/api-keys](https://app.deapi.ai/settings/api-keys)
137
+
138
+ ### Install from PyPI
139
+
140
+ ```bash
141
+ pip install deapi-mcp
142
+ # or run it without installing:
143
+ uvx deapi-mcp
144
+ ```
145
+
146
+ The `deapi-mcp` command starts the HTTP server (see [Running the Server](#running-the-server)).
147
+
148
+ ### Setup from source
149
+
150
+ 1. Clone the repository:
151
+ ```bash
152
+ git clone https://github.com/deapi-ai/mcp-server-deapi.git
153
+ cd mcp-server-deapi
154
+ ```
155
+
156
+ 2. **Choose your Python environment setup:**
157
+
158
+ **Option A: Using `uv` (recommended - fastest)**
159
+ ```bash
160
+ uv pip install -e .
161
+ ```
162
+
163
+ **Option B: Using `pip`**
164
+ ```bash
165
+ pip install -e .
166
+ ```
167
+
168
+ **Option C: Using `conda`**
169
+ ```bash
170
+ # Create conda environment
171
+ conda create -n mcp-server-deapi python=3.11
172
+ conda activate mcp-server-deapi
173
+
174
+ # Install dependencies
175
+ pip install -e .
176
+ ```
177
+
178
+ 3. (Optional) Create a `.env` file for configuration:
179
+ ```bash
180
+ # Copy the example file
181
+ cp .env.example .env
182
+
183
+ # Edit with your preferences (optional - defaults work fine locally).
184
+ # Set DEAPI_JWT_SECRET_KEY before exposing the server beyond localhost.
185
+ # DEAPI_API_BASE_URL=https://api.deapi.ai
186
+ # DEAPI_HTTP_TIMEOUT=30.0
187
+ # DEAPI_MAX_RETRIES=3
188
+ ```
189
+
190
+ ## Usage
191
+
192
+ ### Running the Server
193
+
194
+ The server can run in two modes:
195
+
196
+ **Local Mode** (for use with Claude Desktop on the same machine):
197
+ ```bash
198
+ MCP_HOST=127.0.0.1 python -m deapi_mcp.server_remote
199
+ ```
200
+
201
+ The server starts on `http://localhost:8000`. On loopback it may run without `DEAPI_JWT_SECRET_KEY`
202
+ (it then signs OAuth tokens with a per-process key, so a restart logs clients out).
203
+
204
+ **Remote Mode** (for deployment to a remote server):
205
+ ```bash
206
+ # A fixed signing key is required whenever the server binds beyond loopback
207
+ # (the default host is 0.0.0.0) or uses Redis; without it the server refuses to start.
208
+ export DEAPI_JWT_SECRET_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
209
+ MCP_HOST=0.0.0.0 MCP_PORT=8000 python -m deapi_mcp.server_remote
210
+ ```
211
+
212
+ See the [Remote Deployment](#remote-deployment) section for production deployment options.
213
+
214
+ ### Connecting from Claude Desktop / Claude.ai
215
+
216
+ #### Option 1: Add Connector (Recommended)
217
+
218
+ Both Claude Desktop and Claude.ai support MCP connectors with built-in OAuth authentication.
219
+
220
+ 1. Get your deAPI token from [app.deapi.ai/settings/api-keys](https://app.deapi.ai/settings/api-keys)
221
+ 2. In Claude Desktop or Claude.ai, go to **Customize → Connectors → Add custom connector**
222
+ 3. Fill in the connector details:
223
+
224
+ ```
225
+ Name: deAPI
226
+ Remote MCP server: https://your-server-domain:8000/mcp
227
+
228
+ ▼ Advanced settings
229
+ OAuth Client ID: deapi-mcp
230
+ OAuth Client Secret: YOUR_DEAPI_TOKEN
231
+ ```
232
+
233
+ 4. Click **Add** — Claude will automatically authenticate via OAuth and discover all tools.
234
+
235
+ For details on the OAuth flow, see [AUTH.md](https://github.com/deapi-ai/mcp-server-deapi/blob/main/AUTH.md).
236
+
237
+ ---
238
+
239
+ #### Option 2: Request Headers (no OAuth)
240
+
241
+ Where your Claude plan offers **Request headers** for custom connectors, add the connector with
242
+ no sign-in and the header `Authorization: Bearer YOUR_DEAPI_TOKEN`.
243
+
244
+ Claude Desktop takes remote servers from **Connectors** only: its `claude_desktop_config.json`
245
+ runs local (stdio) servers and is not the place for this server's URL.
246
+
247
+ #### Other clients
248
+
249
+ Open the server's root URL (`https://your-server-domain/`) in a browser: it shows the endpoint
250
+ and a ready-to-copy setup for Claude, ChatGPT, Claude Code, Cursor, VS Code, Codex CLI and
251
+ Gemini CLI.
252
+ Any client that speaks Streamable HTTP works with the endpoint `/mcp` and one of these headers:
253
+
254
+ - `Authorization: Bearer <your deAPI API key>`
255
+ - `X-API-Key: <your deAPI API key>`
256
+
257
+ A key deAPI does not accept is refused with `401` when the client connects.
258
+
259
+ ### Using the Tools
260
+
261
+ **Authentication is handled at the connection level**, not per-tool-call. Tools do NOT accept a `deapi_api_token` parameter.
262
+
263
+ Here's an example workflow:
264
+
265
+ 1. **Get available models**:
266
+ ```
267
+ Use get_available_models to see available models
268
+ ```
269
+
270
+ 2. **Check your balance**:
271
+ ```
272
+ Use get_balance to check remaining credits
273
+ ```
274
+
275
+ 3. **Generate an image**:
276
+ ```
277
+ Use text_to_image with:
278
+ - prompt: "A beautiful sunset over mountains"
279
+ - model: "Flux1schnell"
280
+ ```
281
+
282
+ 4. **Transcribe audio**:
283
+ ```
284
+ Use audio_transcription with:
285
+ - audio: "base64-encoded-audio-or-url"
286
+ - include_ts: true
287
+ ```
288
+
289
+ **Note**: When calling tools via Claude Desktop or MCP SDK, authentication is handled automatically through the server connection (OAuth or HTTP headers). See [AUTH.md](https://github.com/deapi-ai/mcp-server-deapi/blob/main/AUTH.md) for detailed OAuth setup.
290
+
291
+ ## Architecture
292
+
293
+ ### Key Components
294
+
295
+ - **DeapiClient** (`deapi_mcp/deapi_client.py`): HTTP client with auth forwarding, built on the [deAPI Python SDK](https://github.com/deapi-ai/deapi-python-sdk) transport
296
+ - **PollingManager** (`deapi_mcp/polling_manager.py`): Smart adaptive polling for async jobs
297
+ - **Schemas** (`deapi_mcp/schemas.py`): Pydantic models for type safety
298
+ - **Auth code store** (`deapi_mcp/auth_code_store.py`): single-use OAuth authorization codes, in Redis when `DEAPI_REDIS_HOST` is set (so any replica can finish a login), otherwise in process memory
299
+ - **Webhooks** (`deapi_mcp/webhooks.py`): optional HMAC-verified receiver for deAPI completion callbacks, so waiting tools wake on the callback instead of polling (`DEAPI_WEBHOOKS_INTERNAL`)
300
+ - **Tools** (`deapi_mcp/tools/`): Organized tool implementations
301
+ - `audio.py` - Audio transcription, TTS & music generation tools
302
+ - `image.py` - Image generation, transformation, OCR, background removal & upscaling
303
+ - `video.py` - Video generation, image/audio-to-video, description & upscale tools
304
+ - `embedding.py` - Text embedding tools
305
+ - `prompt.py` - Prompt booster tools
306
+ - `utility.py` - Balance, models, status tools
307
+
308
+ ### Smart Adaptive Polling
309
+
310
+ The server uses job-type-specific polling strategies:
311
+
312
+ | Job Type | Initial Delay | Max Delay | Timeout |
313
+ |----------|--------------|-----------|---------|
314
+ | Audio | 1s | 5s | 5 min |
315
+ | Image | 2s | 8s | 5 min |
316
+ | Video | 5s | 30s | 15 min |
317
+ | Embedding | 0.5s | 3s | 2 min |
318
+ | Other (incl. `check_job_status`) | 2s | 10s | 5 min |
319
+
320
+ Polling uses exponential backoff with a configurable multiplier (default: 1.5x,
321
+ `DEAPI_POLLING_<TYPE>__BACKOFF_FACTOR`).
322
+
323
+ ### Error Handling
324
+
325
+ - **HTTP Errors**: Reads are retried (3 attempts) with exponential backoff; a job submission is retried only when it provably was not processed (rate limited, or the connection never opened), so a job is never submitted twice
326
+ - **Long jobs**: one tool call waits at most `DEAPI_TOOL_MAX_WAIT` (45 s, below the 60 s call timeout many MCP clients use). A job still running then returns `success: true, done: false` with its `job_id`, and `check_job_status(job_id, wait_seconds=...)` resumes the wait
327
+ - **Job Failures**: Reported with the API's reason, error code, and whether the job is retryable / was refunded
328
+ - **API Errors**: Properly formatted error responses
329
+
330
+ ## Configuration
331
+
332
+ Configuration can be set via environment variables (prefixed with `DEAPI_`). A variable set to
333
+ an empty value (`DEAPI_REDIS_PORT=`) counts as unset and takes the default. Comments go on their
334
+ own line: some tools (`docker --env-file`, `kubectl create configmap --from-env-file`) keep text
335
+ after a value, `# ...` included, as part of that value. [`.env.example`](https://github.com/deapi-ai/mcp-server-deapi/blob/main/.env.example) lists
336
+ every variable with its default; the block below shows the common ones.
337
+
338
+ ```bash
339
+ # API Configuration
340
+ DEAPI_API_BASE_URL=https://api.deapi.ai
341
+ DEAPI_API_VERSION=v2
342
+
343
+ # HTTP Client
344
+ DEAPI_HTTP_TIMEOUT=30.0
345
+ DEAPI_MAX_RETRIES=3
346
+
347
+ # Seconds one tool call waits before returning done=false and the job_id
348
+ DEAPI_TOOL_MAX_WAIT=45.0
349
+
350
+ # Check a plain API key against deAPI at connect (cached; an API outage lets keys through)
351
+ DEAPI_VERIFY_API_KEYS=true
352
+
353
+ # OAuth for self-registering clients (DCR, CIMD) with a deAPI sign-in screen
354
+ DEAPI_OAUTH_PUBLIC_CLIENTS=true
355
+ # Header with the real client IP from a trusted edge (limits wrong keys on the sign-in screen)
356
+ # DEAPI_CLIENT_IP_HEADER=CF-Connecting-IP
357
+
358
+ # Polling Configuration (override defaults)
359
+ DEAPI_POLLING_AUDIO__INITIAL_DELAY=1.0
360
+ DEAPI_POLLING_AUDIO__MAX_DELAY=5.0
361
+ DEAPI_POLLING_AUDIO__TIMEOUT=300.0
362
+
363
+ # Internal completion webhooks (off by default). The receiver URL must be
364
+ # reachable from api.deapi.ai; a half-configured set refuses to start.
365
+ # Uncomment and fill in all three to turn them on.
366
+ DEAPI_WEBHOOKS_INTERNAL=false
367
+ # DEAPI_WEBHOOK_RECEIVER_URL=https://mcp.example.com/webhooks/deapi
368
+ # Secret the API signs callbacks with: 32-255 characters
369
+ # DEAPI_WEBHOOK_SECRET=
370
+ DEAPI_WEBHOOK_FALLBACK_POLL_INTERVAL=15.0
371
+
372
+ # Shared store for OAuth authorization codes (optional). Unset host = in-memory
373
+ # store, which only works with a single replica. Uncomment and set your own host.
374
+ # DEAPI_REDIS_HOST=redis.example.com
375
+ DEAPI_REDIS_PORT=6379
376
+ # DEAPI_REDIS_PASSWORD=
377
+ DEAPI_REDIS_DB=0
378
+ # Connection scheme: plain | tls (tls needs DEAPI_REDIS_CA_FILE)
379
+ DEAPI_REDIS_SCHEME=plain
380
+ # true = refuse to start without a Redis host
381
+ DEAPI_REDIS_REQUIRED=false
382
+
383
+ # Seconds in-flight tool calls may run after SIGTERM before they are cancelled.
384
+ # Keep it below your platform's termination grace period.
385
+ MCP_GRACEFUL_SHUTDOWN_SECONDS=930
386
+
387
+ # Behind a reverse proxy: the public URL OAuth discovery advertises (without it the
388
+ # 401 challenge points at the bind address), and which proxies' X-Forwarded-* headers
389
+ # are trusted.
390
+ # PUBLIC_BASE_URL=https://mcp.example.com
391
+ # FORWARDED_ALLOW_IPS=*
392
+ ```
393
+
394
+ With internal webhooks on, every job the server submits carries its own receiver URL and the API calls back the moment the job ends; the waiting tool wakes at once, with a slow poll underneath as a safety net. A caller-supplied `webhook_url` takes precedence for that job (the API takes one webhook per job), which then polls normally. A replayed delivery (same `delivery_id`) wakes nobody twice. The job registry is in process memory by default; with several replicas, see [DEPLOYMENT.md](https://github.com/deapi-ai/mcp-server-deapi/blob/main/DEPLOYMENT.md#running-more-than-one-replica).
395
+
396
+ ## Development
397
+
398
+ ### Project Structure
399
+
400
+ ```
401
+ mcp-server-deapi/
402
+ ├── deapi_mcp/
403
+ │ ├── server_remote.py # Streamable-HTTP MCP server
404
+ │ ├── deapi_client.py # HTTP client with auth forwarding
405
+ │ ├── polling_manager.py # Smart adaptive polling logic
406
+ │ ├── schemas.py # Pydantic models
407
+ │ ├── config.py # Configuration management
408
+ │ ├── auth.py # Authentication middleware
409
+ │ ├── fastmcp_auth.py # FastMCP OAuth provider
410
+ │ ├── oauth_endpoints.py # OAuth 2.0 endpoints
411
+ │ ├── auth_code_store.py # OAuth authorization codes (Redis or in-memory)
412
+ │ ├── observability.py # Per-call outcome, injectable metrics sinks
413
+ │ ├── webhooks.py # Internal completion-webhook receiver
414
+ │ └── tools/ # Tool implementations
415
+ │ ├── audio.py # Audio transcription, TTS & music generation
416
+ │ ├── image.py # Image generation, OCR & processing
417
+ │ ├── video.py # Video generation, image/audio-to-video, description & upscale
418
+ │ ├── embedding.py # Text embeddings
419
+ │ ├── prompt.py # Prompt booster
420
+ │ ├── utility.py # Balance, models, status
421
+ │ ├── _price_helpers.py # Resolve parameters from the model card
422
+ │ └── _responses.py # Shared tool response shape
423
+ ├── tests/ # Test suite
424
+ │ ├── __init__.py
425
+ │ └── conftest.py # Pytest fixtures
426
+ ├── pyproject.toml # Dependencies
427
+ ├── Dockerfile # Container build
428
+ ├── docker-compose.yml # Container orchestration
429
+ ├── .env.example # Environment config template
430
+ ├── README.md # This file
431
+ ├── DEPLOYMENT.md # Deployment guide
432
+ ├── AUTH.md # OAuth authentication setup
433
+ └── CLAUDE.md # Claude Code guidance
434
+ ```
435
+
436
+ ### Running Tests
437
+
438
+ Install dev dependencies:
439
+ ```bash
440
+ uv pip install -e ".[dev]"
441
+ ```
442
+
443
+ Run tests:
444
+ ```bash
445
+ pytest
446
+ ```
447
+
448
+ Run smoke tests (requires a running server):
449
+ ```bash
450
+ python tests/smoke_test.py
451
+ ```
452
+
453
+ Run the authentication end-to-end matrix in Docker (server image against a fake deAPI API):
454
+ ```bash
455
+ docker compose -f tests/e2e/docker-compose.yml up --build --exit-code-from e2e
456
+ docker compose -f tests/e2e/docker-compose.yml down
457
+ ```
458
+
459
+ ### Code Formatting
460
+
461
+ Format code with Black:
462
+ ```bash
463
+ black deapi_mcp/ tests/
464
+ ```
465
+
466
+ Lint with Ruff:
467
+ ```bash
468
+ ruff check deapi_mcp/ tests/
469
+ ```
470
+
471
+ Type-check with mypy (strict):
472
+ ```bash
473
+ mypy deapi_mcp
474
+ ```
475
+
476
+ CI runs all three plus the test suite on Python 3.11–3.14.
477
+
478
+ ### Building your own server on the core
479
+
480
+ `deapi_mcp` is importable, so a deployment can assemble its own server from the same tools
481
+ and add what it needs (for example its own metrics) without forking:
482
+
483
+ ```python
484
+ from fastmcp import FastMCP
485
+ from deapi_mcp.server_remote import create_app, register_core_tools
486
+
487
+ server = FastMCP("my-deapi")
488
+ register_core_tools(server) # every deAPI tool
489
+ app = create_app(server, metrics=None) # Starlette app: /mcp, /health, OAuth routes
490
+ ```
491
+
492
+ As with the stock server, set `DEAPI_JWT_SECRET_KEY` first: without it the app refuses to start
493
+ on a non-local host.
494
+
495
+ `metrics` is an optional overlay that instruments tool calls and OAuth and mounts its own
496
+ routes; the stock server (`build_app()`) passes none. `job_registry` replaces the in-process
497
+ registry that completion webhooks wake waiting tools through, for a deployment whose replicas
498
+ share one receiver URL: implement `deapi_mcp.webhooks.JobRegistry` (or subclass
499
+ `JobCompletionRegistry`, relay `signal` to the other replicas and call `wake` where it arrives).
500
+ Its `start`/`stop` run with the app's lifespan. Recorders for per-call outcomes and
501
+ rejected logins plug in through `deapi_mcp.observability`. Settings an overlay can use
502
+ (`DEAPI_METRICS_TOKEN`, `DEAPI_METRICS_REDIS_DB`, `DEAPI_METRICS_PREFIX`) are already defined
503
+ in `deapi_mcp.config`; the core itself never reads them.
504
+
505
+ The package ships type information (`py.typed`) and exposes `deapi_mcp.__version__`.
506
+
507
+ ## API Token Security
508
+
509
+ **Important**: The MCP server does NOT store API tokens. Authentication works as follows:
510
+
511
+ 1. **For Remote HTTP Server**: Authentication is handled via OAuth 2.0 (Authorization Code with PKCE) or HTTP headers (`Authorization: Bearer <key>` or `X-API-Key: <key>`); the key is never read from the URL
512
+ 2. **Token forwarding**: The server forwards authentication to the deAPI API for each request
513
+ 3. **No persistence**: Tokens are used only for the specific request and never persisted or logged
514
+ 4. **Per-connection auth**: Tools do NOT accept `deapi_api_token` parameters - authentication is managed at the connection level
515
+
516
+ Always keep your API tokens secure and never commit them to version control. See [AUTH.md](https://github.com/deapi-ai/mcp-server-deapi/blob/main/AUTH.md) for detailed OAuth setup.
517
+
518
+ ## Remote Deployment
519
+
520
+ For production environments or when you want to host the MCP server on a remote machine, use the remote server mode.
521
+
522
+ ### Quick Start with Docker
523
+
524
+ 1. **Build and run with Docker:**
525
+ ```bash
526
+ docker build -t mcp-server-deapi .
527
+ docker run -d -p 8000:8000 --name mcp-server-deapi -e DEAPI_JWT_SECRET_KEY="<a long random secret>" --stop-timeout 960 mcp-server-deapi
528
+ ```
529
+
530
+ 2. **Or use Docker Compose** (reads `DEAPI_JWT_SECRET_KEY` from the environment or `.env`):
531
+ ```bash
532
+ docker compose up -d
533
+ ```
534
+
535
+ 3. **Configure Claude Desktop to connect:**
536
+ ```json
537
+ {
538
+ "mcpServers": {
539
+ "deapi": {
540
+ "url": "http://your-server-ip:8000/mcp"
541
+ }
542
+ }
543
+ }
544
+ ```
545
+
546
+ ### Manual Remote Deployment
547
+
548
+ 1. **On your remote server:**
549
+ ```bash
550
+ git clone https://github.com/deapi-ai/mcp-server-deapi.git
551
+ cd mcp-server-deapi
552
+ pip install -e .
553
+ export DEAPI_JWT_SECRET_KEY="<a long random secret>"
554
+ python -m deapi_mcp.server_remote
555
+ ```
556
+
557
+ 2. **For production with systemd:**
558
+ ```bash
559
+ # Create /etc/systemd/system/mcp-server-deapi.service
560
+ sudo systemctl enable mcp-server-deapi
561
+ sudo systemctl start mcp-server-deapi
562
+ ```
563
+
564
+ 3. **Behind a reverse proxy (nginx + SSL):**
565
+ ```nginx
566
+ server {
567
+ listen 443 ssl http2;
568
+ server_name mcp.yourdomain.com;
569
+
570
+ ssl_certificate /path/to/cert.pem;
571
+ ssl_certificate_key /path/to/key.pem;
572
+
573
+ location / {
574
+ proxy_pass http://localhost:8000;
575
+ proxy_http_version 1.1;
576
+ proxy_set_header Upgrade $http_upgrade;
577
+ proxy_set_header Connection "upgrade";
578
+ proxy_buffering off;
579
+ proxy_cache off;
580
+ proxy_read_timeout 86400;
581
+ }
582
+ }
583
+ ```
584
+
585
+ ### Cloud Deployment Options
586
+
587
+ - **Railway.app**: Push to GitHub, connect repository, deploy automatically
588
+ - **Fly.io**: `fly launch && fly deploy`
589
+ - **Heroku**: `heroku create && git push heroku main`
590
+ - **DigitalOcean**: Use App Platform or Droplets with Docker
591
+ - **AWS/GCP/Azure**: Deploy with container services (ECS, Cloud Run, Container Instances)
592
+
593
+ For detailed deployment instructions, security considerations, monitoring, and troubleshooting, see [DEPLOYMENT.md](https://github.com/deapi-ai/mcp-server-deapi/blob/main/DEPLOYMENT.md).
594
+
595
+ ## Troubleshooting
596
+
597
+ ### Connection Issues
598
+
599
+ If the server fails to connect:
600
+ 1. Check your API token is valid
601
+ 2. Verify network connectivity to api.deapi.ai
602
+ 3. Check the logs for specific error messages
603
+ 4. For remote servers: verify firewall rules and that port 8000 is accessible
604
+
605
+ ### Job Timeouts
606
+
607
+ If jobs are timing out:
608
+ 1. Check your balance with `get_balance`
609
+ 2. Verify the job type timeout is appropriate
610
+ 3. Use `check_job_status` to check if the job is still processing
611
+
612
+ ### Model Not Found
613
+
614
+ If you get model errors:
615
+ 1. Use `get_available_models` to see available models
616
+ 2. Ensure you're using the correct model name
617
+ 3. Check if the model supports your requested operation
618
+
619
+ ### Remote Connection Issues
620
+
621
+ If remote MCP connection fails:
622
+ 1. Test the server: `curl http://your-server:8000/health` (a bare `GET /mcp` answers 405: the transport is stateless, POST only)
623
+ 2. Check server logs: `docker logs mcp-server-deapi` or `journalctl -u mcp-server-deapi`
624
+ 3. Verify firewall rules and SSL certificates (if using HTTPS)
625
+ 4. Ensure MCP endpoint is accessible from your client
626
+
627
+ ## License
628
+
629
+ This project is licensed under the MIT License - see the [LICENSE](https://github.com/deapi-ai/mcp-server-deapi/blob/main/LICENSE) file for details.
630
+
631
+ ## Changelog
632
+
633
+ See [CHANGELOG.md](https://github.com/deapi-ai/mcp-server-deapi/blob/main/CHANGELOG.md).
634
+
635
+ ## Support
636
+
637
+ For issues related to:
638
+ - **This MCP Server**: [Open an issue](https://github.com/deapi-ai/mcp-server-deapi/issues)
639
+ - **A security vulnerability**: do not open a public issue; see [SECURITY.md](https://github.com/deapi-ai/mcp-server-deapi/blob/main/SECURITY.md)
640
+ - **deAPI Platform**: Visit [docs.deapi.ai](https://docs.deapi.ai/)
641
+ - **MCP Protocol**: Visit [modelcontextprotocol.io](https://modelcontextprotocol.io)
642
+ <!-- mcp-name: io.github.deapi-ai/mcp-server-deapi -->
@@ -0,0 +1,33 @@
1
+ deapi_mcp/__init__.py,sha256=xmDD2cPeNbLvNzTJq7TGe-S_RpU_XoVRtBNcgDH6_OY,1015
2
+ deapi_mcp/auth.py,sha256=I7bzb0ku5kxuc0rYGypT20EKs2syFXxhvF6MONoLEN4,1039
3
+ deapi_mcp/auth_code_store.py,sha256=FsXcWrokXy4GnhRxYxvVCwJNkVTK7IOp0ddTf1PidKs,8273
4
+ deapi_mcp/config.py,sha256=0aK3kwt3falEjxmipcQzhOOYZn1QXRkiNgcC3J54fP4,13892
5
+ deapi_mcp/consent.py,sha256=jW_hA1_IWERrauRsZNMTDcsS1Wt3wFUO7V6QsdMU7fk,21136
6
+ deapi_mcp/deapi_client.py,sha256=2ECgzQMFJNcjJLWAiB1mnNfDLok6_dTWspI_nHx2wHk,17671
7
+ deapi_mcp/fastmcp_auth.py,sha256=EsmaVkI55Sr6Y5Ld6fEGBrywfXAOX_NVggcKQKfSMGs,9108
8
+ deapi_mcp/key_verifier.py,sha256=al3PhUinStzcdzmEfiGIOZaCNayee24GZSugEZZgSWg,8409
9
+ deapi_mcp/landing.py,sha256=Q_-sTs0W9Y9vu__eLQQ5JElEFd9mWK8MybasgDkG2wI,19060
10
+ deapi_mcp/middleware.py,sha256=GnpJWE_HSy_C4Wf0n46CK4rX3Ut1mgs4YhZq6XUSrL0,30407
11
+ deapi_mcp/oauth_clients.py,sha256=tzgalkitfwAGFwTVrNIHRXdAh7GAxhwFh87GXjugH2M,16228
12
+ deapi_mcp/oauth_endpoints.py,sha256=lpO0e7OTLrGqOPmj7Xd9OifotvWt9lBXE6z2FQuGrNE,36136
13
+ deapi_mcp/observability.py,sha256=zzHiaqQBETMUe6b75UOHOrGFuqiYUxxFke1bBn8yd3A,7157
14
+ deapi_mcp/polling_manager.py,sha256=gRZ9lIof3_pwpBYD4rQIfWAF8oXSYXf-B2Lgdur_HeY,14126
15
+ deapi_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
16
+ deapi_mcp/schemas.py,sha256=qC-4wI-gOczzak29kKwmN6Su6xpAB8WKOrUXBJuUR5w,16350
17
+ deapi_mcp/server_remote.py,sha256=ZBpU6y-7NW98NL3IMT4mxZK6ESd5qTUfSmin0jPx8Ys,15917
18
+ deapi_mcp/utils.py,sha256=n79AezH9jB_maz4DPncsfJId1DfZmQepFnc3RXnLfCw,22760
19
+ deapi_mcp/webhooks.py,sha256=L6HZqretH3-4p1e5T0ScL5Phjl-1J7io7SYD3qVf1lI,13480
20
+ deapi_mcp/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
21
+ deapi_mcp/tools/_price_helpers.py,sha256=sVTL0a05r-_CyracZq3ZOZ08PWvtvJIKyOGdpkxzHPY,6321
22
+ deapi_mcp/tools/_responses.py,sha256=XJsirW6_eXlSyvjnfGeepixN229ECpXsD-L6Ro0eTeA,6322
23
+ deapi_mcp/tools/audio.py,sha256=ya8l9sjrwm5Hi9H1F4_NAPfKYXACFaYPTBKq63PY-i0,48952
24
+ deapi_mcp/tools/embedding.py,sha256=9MkqnGKLqi6Lj_vJanmoMBBVNCk-0dhcCLdmKF8gSuc,3673
25
+ deapi_mcp/tools/image.py,sha256=cOLjX0KbJQQ-JBQyA_9WiSDHEIXV6rAFDy4naejqmVI,33909
26
+ deapi_mcp/tools/prompt.py,sha256=TD2aHHDe_bbkaXMZEwQm4P0AyHf3HNH3k4OakcqxPoo,5253
27
+ deapi_mcp/tools/utility.py,sha256=Q81Sy_Gux6Q_2zhiVr6QHU5zt3UczsqIS2SeYlnqIJE,10032
28
+ deapi_mcp/tools/video.py,sha256=igXWOhMcSTmhkD1zLCDaoh_y7QsEr3Zmmg677S2B98M,43522
29
+ deapi_mcp-0.7.0.dist-info/METADATA,sha256=4Yr3mQXaBK4-LReHdBbfOOKkJK546JeQnqbJwRCwFGY,26089
30
+ deapi_mcp-0.7.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
31
+ deapi_mcp-0.7.0.dist-info/entry_points.txt,sha256=9PMzbIxKLQrM5ilkWNnKirk-tQTcsSZdaEbiWlWsSw8,59
32
+ deapi_mcp-0.7.0.dist-info/licenses/LICENSE,sha256=X7qA2gRLcc10Sth0bnd05B6jR_aGiZJIQGrCBK4fQ00,1067
33
+ deapi_mcp-0.7.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ deapi-mcp = deapi_mcp.server_remote:main