Numera-Gen-MCP
Health Uyari
- License — License: GPL-3.0
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 6 GitHub stars
Code Gecti
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
Native Rust MCP server for provider-independent image, video, audio, and 3D generation and editing.
Numera Gen MCP
A local provider-independent MCP server for explicitly selected image, video, audio and 3D work.
Keep your host chat model unchanged. Named connections separate native image protocols, gateway
forwarding, configured GPU ComfyUI workflows and exact fal queue endpoint contracts. No paid POST
retries, hidden uploads, prompt enhancement or automatic provider/model fallback.
Version 0.5.0 lets one .env configure two providers: the main endpoint and an optional fal
section (FAL_API_ENDPOINT, FAL_API_KEY, FAL_MODEL_n_*). Requests are routed by model ID. It runs
on Windows and Linux, x64 and ARM64. Version 0.4.0 removed macOS and routed the legacy image tools
through fal. Version 0.3.0 added
multimedia generation, explicit output kinds/modes, twelve tools and Rust-only maintained tooling. First-party code is now GPL-3.0-or-later; source builds use
Rust 1.100.0, while released binaries need no compiler or language runtime.
Install only the signed 0.5.0 release
with its verification record. Source or an unsigned CI intermediate is not
an installable final release.
The runtime, developer utility, CI driver and maintained tests are Rust. All 51 replaced
Python/JavaScript/PowerShell source files have been removed; historical oracle archives remain
immutable test data. One explicit manual qualification runs tests, Clippy, formatting, release
builds and extracted-binary checks on Windows and Linux, each on x64 and ARM64, plus
production coverage and the authenticated execution collector. The commit's check list links to
those actual jobs; source preparation is separate and never a test pass. Main-only signing promotes
the same qualified binaries without rerunning the heavy suites. The workflow badge is an aggregate,
not proof that preparation, tests and signatures all ran; test evidence records
the exact source/run/attempt. Rust migration records scope and dispositions.
The released 0.5.0 source at ab667a7 passed all six qualification jobs in
run 44317635481, attempt 1:
all 470 frozen cases across five runtime/coverage contexts, with 85.6354% region and
80.7309% branch coverage. The unchanged floors are 85% / 80%. Its four signed native targets
and the signed collector passed
run 44323885497, attempt 1,
at the same commit with the existing signer. The
0.5.0 verification record identifies the actual source, runs, targets and
checksums. 0.3.0 keeps its own record, including its macOS archives. Later edits are not covered by these results.
Historical 0.2.0 retains its original signed bytes and image-only template.
Preserve a working installation until the replacement is signed and the actual host connection is
verified. Signing and trust distinguishes the pinned self-signed publisher from
public OS trust, Apple Developer ID and notarization. CI/SDK readiness does not prove actual GUI
reconnection, live provider entitlement or GPU generation. Independently generated oracle bytes
remain immutable test inputs, not expectations regenerated by the implementation under test.
See migration acceptance and test evidence.
The native target also adds an optional direct HTTP MCP endpoint at http://127.0.0.1:1969/mcp,
a configurable port and a cross-platform native menu. It reuses Numera's own tools, not a remote MCP
proxy. Local authentication is separate from provider keys; bridge remains launcher-free.
HTTP and menu setup has provider-free hosted SDK/CLI verification; actual owner
registration and interactive GUI use remain unverified.
Installation and setup
Use a signed released binary, not a source build or unsigned CI intermediate. The five steps
below target 0.5.0 and its actual numera-gen-mcp executable. Require the published release's
exact-source qualification, signatures and matching checksums before installation; the
verification record holds both. The immutable image-only 0.2.0 release
retains numera-image-gen-mcp and its own template; never rename those signed bytes or copy media
settings into that old version. Historical installation and trust
evidence remains available.
You need a local MCP-capable client, a writable installation folder, and an endpoint/key/model
that actually supports your intended image operation. Hosted generation also needs network access;
ComfyUI needs its own configured installation. Nothing in setup authorizes a paid request.
1. Download the ready native build
Download native 0.5.0 from this
repository's Releases page and verify it against the published .sha256 sidecar; an unavailable or
unverified archive is not permission to use an unsigned artifact.
Normal usage needs no Node.js, npm, Rust toolchain, Python, compiler or local build.
Your MCP client runs the executable directly. ComfyUI remains an optional separately installed backend,
not a bundled runtime.
Choose the archive for your actual OS/CPU:
| OS | CPU | Archive suffix |
|---|---|---|
| Windows | Intel/AMD 64-bit | numera-gen-mcp-0.5.0-x86_64-pc-windows-msvc.zip |
| Windows | ARM64 | numera-gen-mcp-0.5.0-aarch64-pc-windows-msvc.zip |
| Linux GNU | Intel/AMD 64-bit | numera-gen-mcp-0.5.0-x86_64-unknown-linux-gnu.tar.gz |
| Linux GNU | ARM64 | numera-gen-mcp-0.5.0-aarch64-unknown-linux-gnu.tar.gz |
Published compatibility and minimum OS versions must match that Release's actual native CI evidence.
A Linux binary is not proof that Claude Desktop itself supports Linux.
2. Verify and extract
Download the archive and its .sha256 sidecar from the same Release. Match the SHA-256 before
extracting. The archive contains bin/numera-gen-mcp (Windows: .exe), license/notices,
configuration templates, schemas and examples. Extract into a writable installation folder you own;
do not overwrite an existing private configuration or outputs.
Windows PowerShell, replacing the downloaded filename:
$archive = './numera-gen-mcp-0.5.0-x86_64-pc-windows-msvc.zip'
$expected = ((Get-Content -LiteralPath "$archive.sha256" -Raw -Encoding utf8).Trim() -split '\s+')[0]
if ($expected -notmatch '^[a-fA-F0-9]{64}$' -or (Get-FileHash -Algorithm SHA256 -LiteralPath $archive).Hash -ine $expected) { throw 'Release checksum mismatch; do not extract or run.' }
Use the sidecar for that exact version and target. Check the Release's source and approved signer
pins too; a matching checksum does not authenticate an untrusted replacement sidecar.
Linux, from the download folder:
sha256sum -c numera-gen-mcp-0.5.0-x86_64-unknown-linux-gnu.tar.gz.sha256
Extract into a new directory using your OS archive extractor. Archives contain one top-levelnumera-gen-mcp-0.5.0-<target>/ folder. That folder is the installation root: it containsbin/, .env.example, docs/ and manifest.json. Open a terminal there for the relative commands
below. You may give that extracted folder a stable installation name before registering it, for
example C:/tools/numera-gen-mcp or $HOME/tools/numera-gen-mcp; keep its contents together.
On Linux, tar -xzf ARCHIVE.tar.gz preserves executable permissions. Confirm the binary before
adding credentials (Windows PowerShell, from the installation root):
& './bin/numera-gen-mcp.exe' --version
Linux:
./bin/numera-gen-mcp --version
Expect version 0.5.0, publisher KiaroSama and the exact source SHA recorded in that Release.
Do not accept a different build source merely because its version string matches.
Check signature verification and self-signed trust limits before running a download;
a checksum alone is not a public OS-trust certificate. Do not blindly bypass security warnings or
install a new trust root. Managed .runtime/temp and .runtime/cache stay inside the installation
root; it must remain writable. No launcher, admin install or global cache is required.
3. Create your private configuration
Copy the extracted release's own .env.example to .env in the installation root, not bin/
and not your client's working directory. Edit it in a UTF-8 text editor. Existing installation?
Back up and retain its selected private config and data instead of replacing them with a template.
Windows PowerShell:
[IO.File]::Copy((Join-Path $PWD '.env.example'), (Join-Path $PWD '.env'), $false)
Linux:
(set -o noclobber; umask 077; cat .env.example > .env)
Edit .env: set API_ENDPOINT, API_KEY and MODEL_1_ID / MODEL_1_NAME. The 0.3.0-and-later template has
three slots with ENABLED, image defaults and optional paired OUTPUT_TYPES / MODES declarations.
Leave both declaration fields empty for existing image configurations.
Extra slots are disabled; fill their exact
IDs/names before setting ENABLED=true. At least one model must be enabled; the first enabled slot
is the default. Names are display labels, never routing aliases. Empty output fields preserve provider
defaults; explicit tool arguments override them. Use only native values your selected model supports.
API_ENDPOINT=https://gateway.example/v1
API_KEY=replace-with-your-private-key
PROFILE=openai-images
MODEL_1_ID=provider/exact-image-model
MODEL_1_NAME="My image model"
MODEL_1_ENABLED=true
MODEL_1_OUTPUT_FORMAT=
MODEL_1_SIZE=
MODEL_1_QUALITY=
The endpoint is any valid HTTP(S) API prefix: hosted, localhost or reverse-proxy, not a fixed port.
Do not include /responses or /images/generations. Generic openai-images is the default; explicitly
choose PROFILE=omniroute or PROFILE=9router for gateway-specific contracts. An endpoint/key pair
alone cannot turn a chat-only API into an image API.
For Responses use simple-responses.env.example:
PROFILE=openai-responses plus ORCHESTRATION_MODEL, separate from the selected image model.
Native Gemini/Gemini Interactions/OpenRouter Images profiles are also available; see
configuration. Editing is enabled only by its verified native contract,
not guessed from an endpoint/model ID.
Outputs/state/logs/inputs sit beside the selected config. This plaintext-key file is ignored and
excluded from packages: never share, sync or commit it. On Linux restrict access:
chmod 600 .env
Save and call list_models again: valid model/endpoint settings reload without restarting.
Invalid or partially saved files keep the last valid configuration and emit a redacted warning.
Active jobs retain their original connection; reload never submits or retries an image request.
Storage/logging/input-root/global-policy changes and the bounded 64-snapshot limit require restart.
Legacy compact and advanced JSON remain supported for existing installations.
What each .env field means
Values may be quoted as in .env.example. An empty value ("") means unset, notauto or zero. Boolean fields accept exactly "true" or "false"; yes, 1 and 0 are invalid.
Keep key names unchanged: unknown keys and duplicate assignments reject the saved configuration.
Connection and API protocol
| Field | Purpose | Required / default |
|---|---|---|
API_ENDPOINT |
Your image API's HTTP(S) base prefix, such as https://gateway.example/v1. Numera appends the operation path. Do not include /images/generations, /images/edits or /responses. |
Required. No fixed host or port. |
API_KEY |
Private credential for that endpoint. Gemini sends x-goog-api-key; other released compact profiles send bearer authentication. Never paste a real key into host config, prompts or public files. |
Required, nonblank, without newline/NUL. |
PROFILE |
Selects the actual API contract. Accepted: openai-images, omniroute, 9router, openai-responses, gemini, gemini-interactions, openrouter-images. Gateway profiles use Images with their specific forwarding rules. |
Empty/omitted: openai-images. Choose the protocol your endpoint actually exposes. |
ORCHESTRATION_MODEL |
Exact conversation-model ID that drives a Responses request. It is separate from the image model selected through MODEL_n_ID. |
Required for openai-responses; leave empty for every other profile. |
Model slots: replace n with 1, 2, 3, ... up to 100
The same image-default fields and optional paired media declarations apply to every slot. Slots are ordered numerically; the first enabled model is the
default. A nonempty slot needs both ID and NAME, including disabled placeholders. At least one model
must be enabled, and IDs must be unique. A configured model is not proof of account entitlement.
| Field | Purpose | Required / default |
|---|---|---|
MODEL_n_ID |
Exact provider model ID sent to the API, including any required provider prefix. | Required for a nonempty slot; up to300 characters. |
MODEL_n_NAME |
Friendly name the agent displays through list_models. It does not change routing. |
Required for a nonempty slot; up to100 characters. |
MODEL_n_ENABLED |
Enables the slot. false hides it from configured listing and denies its ID for submission. |
Empty/omitted: true. Template slots2 and3 explicitly use false. |
MODEL_n_OUTPUT_FORMAT |
Default output format: png, jpeg or webp, only if the selected route supports it. |
Empty: provider default, nothing sent. |
MODEL_n_SIZE |
Default native pixel dimensions, for example 1024x1024, if accepted by that API/model. Numera does not resize the returned original to match. |
Empty: provider default; nonblank values up to100 characters. |
MODEL_n_QUALITY |
Default native quality value, for example auto, low, medium or high on models supporting those values. It is not a universal quality scale. |
Empty: provider default; nonblank values up to100 characters. |
The optional MODEL_n_OUTPUT_TYPES / MODEL_n_MODES pair requires 0.3.0 or later and is documented in
Video, audio and 3D. Both fields must be nonempty together or empty together.
Adding them to an old 0.2.0 configuration rejects it; retain that release's own template until upgrading.
Explicit image-tool arguments override these model defaults. Native Gemini uses aspect_ratio andimage_size tool arguments instead of Images-style SIZE/QUALITY; generateContent does not accept a
requested output format. Unsupported settings fail rather than silently disappearing.
Optional reference-editing contract
These fields describe a verified Images input contract, not a switch that grants the model editing
capability. Leave all five empty for generation-only use or when your route has not been verified.
Native protocols may already carry references independently; these fields cannot add native mask
support to an adapter that does not implement it. Any nonempty edit setting requires EDIT_MODE.
| Field | Purpose | Required / default |
|---|---|---|
EDIT_MODE |
multipart: upload reference bytes to /images/edits; json: inline references in JSON to /images/edits; generation: inline references through /images/generations. Explicit gateway contracts may override this mapping. |
Empty: no explicit Images edit contract. |
EDIT_ENCODING |
Reference field shape expected by the route: image, image[], images, image_urls or input_references. For multipart, use image or image[]; JSON/generation must match the provider's documented field. |
Required when EDIT_MODE is set. |
EDIT_MAX_REFERENCES |
Maximum reference count declared for the edit contract; other route/model limits can be stricter. | Integer1–32; empty:1. |
EDIT_MASKS |
Declares verified mask forwarding. true alone cannot bypass an adapter/gateway restriction. |
Empty: false. |
EDIT_MASK_POLARITY |
Which mask pixels are editable: transparent-edit = transparent pixels; white-edit = white pixels; black-edit = black pixels. Must match the provider. |
Needed for mask/rectangle editing; no inferred default. |
For a verified standard Images edit/mask route, a typical setup is:
EDIT_MODE="multipart"
EDIT_ENCODING="image"
EDIT_MAX_REFERENCES="1"
EDIT_MASKS="true"
EDIT_MASK_POLARITY="transparent-edit"
Do not enable this example blindly on a gateway. edit_region and target_language belong toedit_image tool arguments, not .env fields. Editing examples and
advanced configuration explain route limits and additional JSON settings.
Save .env and call list_models again to apply a valid change; no image is submitted just by saving.
Optional second provider: fal
The same .env can hold a separate fal section beside the main provider. It becomes a second
connection named fal, with its own endpoint, key and model list; the main section stays connectiondefault. Fill both fal fields to enable it, or leave them empty to disable it:
FAL_API_ENDPOINT=https://queue.fal.run
FAL_API_KEY=replace-with-your-private-fal-key
FAL_MODEL_1_ID=fal-ai/flux/dev
FAL_MODEL_1_NAME="FLUX dev (text-to-image)"
FAL_MODEL_1_ENABLED=true
FAL_MODEL_1_OUTPUT_TYPES=image
FAL_MODEL_1_MODES=text-to-image
FAL_MODEL_n_* accepts the same fields as MODEL_n_*. FAL_API_ENDPOINT selects direct queue mode
(Key authentication) for https://queue.fal.run or OmniRoute's /v1/fal gateway (Bearer
authentication) for an HTTP(S) /v1 or /api/v1 prefix, so the fal section has no PROFILE; EDIT_*
and ORCHESTRATION_MODEL apply to the main section only. Either section may be left empty, but not both; with only fal
configured, fal is the default connection. A tool call without connection goes to the section that
lists the requested model ID. An ID listed in both sections, or in neither, is refused before anything
is sent, so pass connection explicitly in that case.
4. Register with your MCP client
Registration is one-time. Preserve unrelated settings and back up the host file before merging only
Numera's entry. The exact current client entry is numera-gen-mcp; use that name consistently. If you
already have numera-image-gen, update that selected entry instead of adding a second server against
the same state. The registration command (0.3.0 and later) manages exactly numera-gen-mcp; it never removes
older entries implicitly. Use either manual configuration or explicit entry-scoped registration, not both. After registration no launcher needs to be opened: the host runs the executable
with args: ["bridge"], which starts MCP over stdin/stdout. No background daemon or listening port
must be started first.
Claude Desktop
Merge this into the actual claude_desktop_config.json; the paths are examples, not your machine's
installation. Keep every other mcpServers member unchanged:
{
"mcpServers": {
"numera-gen-mcp": {
"command": "C:/tools/numera-gen-mcp/bin/numera-gen-mcp.exe",
"args": ["bridge"]
}
}
}
The executable finds .env first, then config.local.json, in its installation root (parent of bin/),
not Claude's working directory. Existing user-config fallback and an explicit absolute NUMERA_CONFIG
remain supported. If private configuration is elsewhere, add only this entry's env:
{
"NUMERA_CONFIG": "C:/private/numera/.env"
}
Never put the API key in host settings or arguments; args stays ["bridge"].
Use Desktop's Edit Config to locate its actual settings, fully quit/reopen the app and callhealth_check plus list_connections to confirm the selected configuration.
Claude clients has the registration and reconnect details.
Claude Code
Linux, from the extracted installation root:
claude mcp add --transport stdio --scope user numera-gen-mcp -- "$PWD/bin/numera-gen-mcp" bridge
Windows PowerShell, with your actual executable:
claude mcp add --transport stdio --scope user numera-gen-mcp -- 'C:/tools/numera-gen-mcp/bin/numera-gen-mcp.exe' bridge
For project scope, use the same command with --scope project instead of --scope user; review
and preserve the existing .mcp.json. Current project JSON examples
use the current numera-gen-mcp binary name (0.3.0 and later); keep the immutable legacy name only for historical 0.2.0. CLI user
scope is distinct from Claude Desktop chat's config. Restart/reconnect the selected client after
registration; endpoint/model saves then reload through list_models, without another submission.
Codex and other local MCP clients
Merge only this table into the actual ~/.codex/config.toml (or trusted project's .codex/config.toml),
backing it up first and replacing example paths with your installation. A 360-second tool timeout
allows the server's ordinary long-operation timeout to report its receipt instead of the client's
60-second default ending first. Do not add duplicate tables.
[mcp_servers.numera-gen-mcp]
command = "C:/tools/numera-gen-mcp/bin/numera-gen-mcp.exe"
args = ["bridge"]
startup_timeout_sec = 10
tool_timeout_sec = 360
env = { NUMERA_CONFIG = "C:/tools/numera-gen-mcp/.env" }
On Linux use actual absolute POSIX paths. The alternative CLI command below adds the stdio
entry; set tool_timeout_sec = 360 in its resulting table afterward, then restart/reconnect Codex:
codex mcp add numera-gen-mcp -- "$PWD/bin/numera-gen-mcp" bridge
Cursor/Windsurf use their local mcpServers configuration. Kiro uses mcpServers with its disabled
flag. Hermes uses mcp_servers. VS Code-native .vscode/mcp.json uses servers and type: "stdio".
For those clients set command to the native binary and args to ["bridge"]; optionally add the
absolute private NUMERA_CONFIG in that member's env. Do not translate top-level keys between
clients blindly. OpenCode uses mcp with type: "local" and a command array containing the binary
and "bridge". Existing host trust/approval and installation support remain the host's responsibility.
Optional native entry-scoped registration (never automatic at startup):
./bin/numera-gen-mcp register --client ClaudeDesktop --host-config /absolute/claude_desktop_config.json --config /absolute/numera/.env --dry-run
Review the dry run first. Removing --dry-run deliberately updates only Numera with an exact-byte
backup and concurrent-change protection. --remove removes only that member, never user images or
application data. Ambiguous TOML, links, active registration locks and invalid host JSON are rejected.
These instructions are not registration performed by this repository task.
Current-name replacement (0.3.0 and later)
The new build is numera-gen-mcp.exe on Windows and numera-gen-mcp on Linux; its exact
host entry is numera-gen-mcp. Do not switch until that build is signed, qualified and installed.
The commands above use the real current executable (0.3.0 and later). An old 0.2.0 binary cannot be upgraded by renaming it.
After the qualified new installation is verified, replace only the selected Numera entry:
{
"mcpServers": {
"numera-gen-mcp": {
"command": "C:/tools/numera-gen-mcp/bin/numera-gen-mcp.exe",
"args": ["bridge"],
"env": {
"NUMERA_CONFIG": "C:/tools/numera-gen-mcp/.env",
"TEMP": "C:/tools/numera-gen-mcp/.runtime/temp",
"TMP": "C:/tools/numera-gen-mcp/.runtime/temp",
"TMPDIR": "C:/tools/numera-gen-mcp/.runtime/temp"
}
}
}
}
Replace every example root with the same actual project directory. The binary's installation root
(parent of bin/) owns .runtime/temp and .runtime/cache, regardless of the config path or host
working directory; there is no extra cache environment key. Desktop,
project JSON and Codex TOML use the same new name.
Back up and explicitly migrate a selected old numera-gen/numera-image-gen entry rather than running
two processes against the same state. Registration manages only the exact current entry; it does not
remove legacy entries automatically. Keep the working runtime and data until actual reconnection.
5. Verify the connection before approving an image
First check local configuration/storage/declared credentials without contacting a provider. Windows
PowerShell, replacing the absolute config path:
& './bin/numera-gen-mcp.exe' readiness --config 'C:/tools/numera-gen-mcp/.env'
Linux:
./bin/numera-gen-mcp readiness --config "$PWD/.env"
Expect local_ready: true and exit 0 for a valid writable installation. Missing credentials or
connection blockers return exit 2; invalid arguments/configuration return exit 1. This is not a
successful generation or actual host reconnection.
After restarting the MCP client, ask it to call health_check with probe=false, list_connections
and list_models with refresh=false. Inspect get_model_capabilities for the exact selected model.
Expect twelve tools (0.3.0 and later), the selected connection and your configured model name. Only if you
want to test the provider's read-only catalog, add --probe to the readiness command; it performs
provider GETs but never submits a generation. Readiness does not prove model entitlement or quality.
Logs go to stderr/files, never MCP stdout.
When you explicitly approve potentially billable work, ask: Use Numera generate_image once to create
a blue mug beside an orange. count=1; request_id=my-first-image-001. Reuse that ID for the same
logical request only. Never give an unknown outcome a new ID just to retry it.
Outputs keep the provider's original bytes and verified MIME/dimensions/hash. A bounded preview is
optional; a remote/cloud host cannot inherently read local paths or launch a local stdio executable.
Update and troubleshoot
Download the next verified Release and checksum into this project's own download/work directory.
Preserve private config, originals, receipts/journals and migration snapshots. Quit/reconnect the MCP
host around replacing the executable; never replace data folders with a fresh empty installation.
Keep the old executable until the new host connection actually succeeds. Only then remove reviewed
obsolete project-local runtime/dependency/temp/cache paths. Never clear another project's or a
system/global cache.
| Problem | Check |
|---|---|
| Server not visible | Actual absolute binary path, args: ["bridge"], correct host file and trust/reconnect |
| Startup exits | Private config validity, writable project-contained scratch and configured storage; inspect redacted log |
| No configured models | At least one enabled model with exact ID and readable name |
| Catalog/probe fails | Selected route, API prefix, credentials and account; this is not generation failure proof |
| Unknown outcome | Inspect the same receipt with get_job; do not submit a replacement automatically |
If a 0.2.0 installation reports unknown OUTPUT_TYPES / MODES or PROFILE=fal, restore its own
release template; these belong to 0.3.0 and later. A missing numera-gen-mcp filename is the same version
mix-up: use numera-image-gen-mcp for 0.2.0. A manually launched bridge waiting on stdin is normal;
use readiness for diagnosis and let the MCP host own bridge startup/shutdown.
Protocols and tools
OpenAI-compatible vs Anthropic-compatible API
Numera currently submits images through evidenced image APIs, including OpenAI-compatible Images
and Responses. Using Claude as the MCP host does not require an Anthropic image endpoint: Claude
calls Numera over MCP, and Numera calls your selected image backend independently.
The standard Anthropic POST /v1/messages contract accepts images for vision but does not define a
native generated-image output or OpenAI-style image_generation tool. A generic Anthropic-compatible
chat endpoint is therefore not sufficient for image generation. Numera does not claim such an adapter.
The examined OmniRoute3.8.51 Messages path delegates to chat; image-only models are rejected and its
Claude response translation does not preserve generated image content. Use its supported
/v1/images/generations route instead. A future Messages image-output adapter needs an explicit
gateway extension defining request options, authentication and final image bytes; no protocol
inference, silent parameter dropping or automatic fallback is permitted.
Sources: Anthropic Messages,
vision input, and
pinned OmniRoute response conversion.
Generic Images, OmniRoute, 9router, Gemini generateContent, Gemini Interactions, OpenAI Responses image
tools, dedicated OpenRouter Images, opt-in chat image output and explicitly bound ComfyUI API graphs.
Compatibility/limitations distinguish protocol evidence from account/model
availability. Antigravity refs are blocked at the examined gateway versions that drop input images.
12 source-defined tools: health_check, list_connections, list_models, get_model_capabilities,
generate_image, edit_image, get_job, cancel_job, list_outputs, get_output_info, generate_media and
get_media_output_info. The published 0.2.0 has only the original ten. Use one request_id per logical operation
and reuse it on host retries. Unknown outcomes never automatically resubmit. Native batches require
verified limits. Edit sources are typed output_id/path/url/data_url objects; no ambiguous strings.
Saved originals provide owned IDs, paths, actual MIME/dimensions/bytes/alpha/SHA256. Optional bounded
previews are derivatives. Local paths are not automatically accessible to cloud hosts. Prompts/input
bytes preserved unless explicit in-image translation or upscale instructions are requested; provider policy/terms still apply. Read privacy.
Video, audio and 3D
Declare both output kinds and exact transformations for each model. Full JSON usesmodelOverrides.<exact-id>.outputTypes and modes; compact JSON uses models[].output_types andmodes; dotenv uses comma-separated MODEL_n_OUTPUT_TYPES and MODEL_n_MODES. Kinds areimage, video, audio, 3d. Omitting both declarations preserves legacy image configuration;
it does not silently enable a new media route. A configured mode is not account entitlement.
The full fal example declares every implemented endpoint's output kinds and modes,
including image sidecars and the GLB geometry selection for Rodin. It reads the credential from FAL_KEY;
no real credential belongs in a public example. Configuration alone does not submit a request.
For compact dotenv configuration, use the fal section with https://queue.fal.run (or an OmniRoute/v1 gateway prefix) and an exact implemented endpoint:
FAL_API_ENDPOINT=https://queue.fal.run
FAL_API_KEY=replace-with-your-private-fal-key
FAL_MODEL_1_ID=fal-ai/stable-audio
FAL_MODEL_1_NAME="Audio generation"
FAL_MODEL_1_ENABLED=true
FAL_MODEL_1_OUTPUT_TYPES=audio
FAL_MODEL_1_MODES=text-to-audio
A pre-0.5.0 file that selects PROFILE=fal on the main API_*/MODEL_n_* keys still loads as
connection default; it cannot be combined with FAL_* keys.
A tool request for that explicit configuration is:
{
"request_id": "my-audio-001",
"model": "fal-ai/stable-audio",
"mode": "text-to-audio",
"prompt": "Gentle rain on a wooden roof",
"parameters": {},
"wait": false
}
Submit through generate_media only after authorizing the destination and cost. Use the samerequest_id with get_job; cancellation does not verify a refund. Typed references carry kind,role and exactly one output_id, path, url or data_url. Numera validates original bytes and
forwards inline data only where that exact endpoint implements the role; it makes no hidden upload.
Implemented endpoint bindings cover text/image-to-image, text/image/video-to-video, text/audio-to-audio,
and text/image/3D-to-3D paths individually, not all possible conversions. Unsupported endpoint/mode,
reference, parameter or format fails explicitly. Initial original-byte validation covers PNG/JPEG/WebP/GIF,
PCM/IEEE-float WAV, self-contained single-visual-track nonfragmented MP4, and a bounded self-contained
GLB 2.0 mesh subset. Audio tracks in MP4, fragmented video, compressed/animated/skinned GLB and other
media formats are not supported by these validators. Structural validation is not full decode,
rendering, semantic quality or live-provider proof. Provider artifacts outside these limits can yield
partial or failed storage after generation; inspect the receipt, never resubmit automatically.
For the exact Flux dev image endpoints, explicit effective num_images, output_format and numericimage_size requirements are saved with the request. Mismatching originals remain unchanged and
produce deviations with overall partial status; successful storage remains completed.
Local recovery uses that saved requirement snapshot, not later configuration defaults. Omitted
provider defaults, named size presets and other media parameters are not conformance guarantees.
get_media_output_info checks owned original bytes, actual MIME, kind, role, format, byte count,
SHA-256 and available kind-specific metadata. No invented image dimensions for audio or meshes.
Configuration records the exact endpoint and declaration contracts.
Image-to-image, comic and selected-region editing
Use edit_image with approved reference_images for image-to-image/comic edits and authorized watermark removal. Add target_language
for translation replacing text inside the image; add edit_region={x,y,width,height} for an absolute
pixel rectangle on the first reference. A verified native mask route is required for region editing.
Use upscale=true with one reference and a larger numeric size to ask the same image model for a
higher-resolution edit; verified reference/size support is required, and actual size deviations remain
visible. Unsupported masks/parameters fail before submission. No local output resizing is performed.
Examples, coordinate rules and limitations. Actual translation quality needs
a real authorized sample; offline wire/mask tests are not semantic proof.
Ratios, resolutions and custom dimensions
Ask the agent to call get_model_capabilities for the exact model. Its dimensions result includes
built-in ratio presets, sourced model-native ratios/tiers/pixel sizes, custom-size support status and
separate selected-route parameter acceptance. Presets alone are suggestions, not support claims.
Unknown model IDs have unknown native dimensions rather than invented universal4K support.
For documented Gemini3.1 Flash Image,14 ratios include1:1,16:9,9:16,3:2,2:3 and21:9; native tiers
are0.5K/1K/2K/4K. The complete per-ratio pixel table is returned by the tool.4K16:9 maps to5504x3072,
not3840x2160. The examined OmniRoute path accepts1K/2K/4K but not0.5K; generic Images does not accept
undeclared aspect_ratio/image_size. Arbitrary custom pixels are not a native Gemini contract:
select a documented ratio+tier, or use an independently verified custom-size model. Numera never
silently resizes output to match. Dimension selection details.
Documentation
Configuration · OmniRoute · 9router ·
Claude · Codex · Windows/WSL · Linux ·
Architecture · Testing · Requirements ·
References
Native private maintenance
Version 0.3.0 adds Windows numera-dev protect-secret --path ABSOLUTE_FILE with hidden
CurrentUser DPAPI input and exclusive owner-only output. --dry-run/--what-if reads no secret and
creates no file. Native identity inspect and identity create --dry-run, both with explicit--root ABSOLUTE_ROOT, inspect local conditions without creating custody or logs. Actual identity
creation/checking requires separately selected qualified native crypto-library inputs; no command
runs automatically or rotates the approved signer. Credential details and
identity/custody limits describe the exact boundaries.
These commands and the all-51-file Rust tooling migration require a qualified 0.3.0 or later release;
they are not features of the historical 0.2.0 developer binary. Standard OS/native third-party tools remain permitted;
substantive first-party bootstrap/preparation logic belongs to the Rust driver, not hidden scripts.
Logs and troubleshooting
New UTF8 JSON log per execution: numera-gen-mcp_YYYY-MM-DD_HH-mm-ss_UTC-<pid>-<uuid>.log, UTC
ISO8601 timestamp, INFO/WARNING/ERROR/DEBUG and component. Default directory configured/per-user;
14-day own runtime-log retention, initialization falls back stderr. Prompts/keys/auth/cookies/Base64/
signed query data/original paths not logged. Every accepted tool call records start/completion/failure,
run_id/call_id correlation, elapsed milliseconds and safe error code/stage; never arguments or raw
provider bodies. Event timestamp/level/component/run_id cannot be overwritten by context. DEBUG never
relaxes redaction. Attach only sanitized logs.
Catalog failure is not generation failure. Check route/base prefix/key/model before new authorization.
A text-only gateway cannot edit just because its model has native vision. Distinguish provider rejection,
partial stream, host timeout, OAuth/project/account problems, uncertain billing and storage permissions.
Never retry unknown generation automatically. Cancel waiting does not prove upstream cancellation/refund.
License
Numera Gen MCP is licensed under GPL-3.0-or-later. You may redistribute it and/or modify it
under the GNU General Public License as published by the Free Software Foundation,
either version 3 of the License, or (at your option) any later version.
It is distributed without any warranty; see the complete GPLv3 text.
Donate
If this project helps you, donations are appreciated.
| Currency | Network | Address |
|---|---|---|
| Bitcoin (BTC) | Bitcoin | bc1qmth5m03pu5hujw5xw5jmywam3jj3sqwqupesdt |
| USDT, BNB, USDC, etc. | BEP20 | 0x0Bd0BA443a8B9cf15922bf7f0Bb0a4b495fD06Ef |
| USDT, TRX, USDC, etc. | TRC20 | TWBA3xFTqgZAeAYMxqo85xWnzvty3DcAhw |
| Ethereum (ETH) | ERC20 | 0x0Bd0BA443a8B9cf15922bf7f0Bb0a4b495fD06Ef |
| TON | TON | UQCN8Umo_OfOWqImZetQsrNStPcmLkMAKajFyiCOhso23NDb |
| Litecoin (LTC) | LTC | ltc1qntqnnrunadurnw4cshv3qgspywrueyyeyngwuy |
| Solana (SOL) | Solana | 7B2wkczUjmkDhETwQuknBL8sUsbuV7nErxc317TmQuwR |
| Polygon (POL) | Polygon | 0x0Bd0BA443a8B9cf15922bf7f0Bb0a4b495fD06Ef |
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi