Related Pages

Related topics: Tools & Multi-Provider Model Routing

Repository Overview & System Architecture

Purpose and Scope

omni-ai-mcp is an MCP (Model Context Protocol) server that exposes multiple AI model providers and a registry of reusable tools under a single, unified interface. Its primary role is to act as a bridge between MCP-compatible clients (such as IDE assistants and agent runtimes) and heterogeneous upstream model providers, allowing clients to switch providers, query models, and invoke tools without hard-coding provider-specific APIs. Source: app/server.py:1-40

The project explicitly targets multi-provider orchestration. It ships dedicated service modules for at least two major providers — Google's Gemini and OpenRouter — and centralizes model metadata in a shared registry. Tools exposed via MCP are likewise registered through a dedicated registry, which keeps server wiring declarative and extensible. Source: app/services/gemini.py:1-30, Source: app/services/openrouter.py:1-30, Source: app/services/model_registry.py:1-25, Source: app/tools/registry.py:1-25

High-Level Architecture

The codebase follows a layered structure that separates transport, configuration, business services, and tool exposure:

• Transport / Entry point — app/server.py boots the MCP server and dispatches incoming requests to the appropriate service or tool. Source: app/server.py:20-60
• Configuration layer — app/core/config.py centralizes environment-derived settings (API keys, provider selection, runtime options) so that services do not read os.environ directly. Source: app/core/config.py:1-40
• Provider services — app/services/gemini.py and app/services/openrouter.py encapsulate provider-specific API calls, request/response shaping, and error translation. Source: app/services/gemini.py:25-70, Source: app/services/openrouter.py:25-70
• Model registry — app/services/model_registry.py provides a single source of truth for available models, their capabilities, and the provider that serves them. Source: app/services/model_registry.py:20-55
• Tool registry — app/tools/registry.py enumerates tools exposed over MCP, mapping tool names to their handler implementations. Source: app/tools/registry.py:15-45

flowchart TD
    Client[MCP Client] --> Server[app/server.py]
    Server --> Config[app/core/config.py]
    Server --> ToolReg[app/tools/registry.py]
    Server --> ModelReg[app/services/model_registry.py]
    ModelReg --> Gemini[app/services/gemini.py]
    ModelReg --> OpenRouter[app/services/openrouter.py]
    ToolReg --> Handlers[Tool Handlers]

Module Responsibilities

Server Entry Point

app/server.py is the orchestrator. It initializes configuration, registers tools from the tool registry, wires model providers from the model registry, and handles MCP protocol-level concerns (handshake, tool listing, invocation routing). Source: app/server.py:30-80

Configuration

app/core/config.py defines how runtime settings are resolved. By isolating configuration, the rest of the codebase can depend on a typed configuration object instead of scattered os.getenv calls, which simplifies testing and provider switching. Source: app/core/config.py:20-60

Provider Services

Both app/services/gemini.py and app/services/openrouter.py share a common pattern: they expose a thin, provider-specific adapter that translates between MCP-facing tool calls and the provider's native SDK or HTTP API. Each service is responsible for authentication (via config-injected keys), request construction, response parsing, and surfacing provider errors in a uniform shape. Source: app/services/gemini.py:40-90, Source: app/services/openrouter.py:40-90

Registries

The two registries serve complementary roles. The model registry answers "which model can do what, and which provider serves it?" — useful for capability-aware routing and for clients that want to enumerate models. Source: app/services/model_registry.py:30-65 The tool registry answers "which MCP tools exist, and how do I invoke them?" — it is the contract surface for client integrations. Source: app/tools/registry.py:25-55

Dependency and Packaging Notes

Dependencies are declared in pyproject.toml, and a companion requirements.txt is provided for pip install -r requirements.txt workflows. Community issue #1 reports that requirements.txt has historically drifted out of sync with pyproject.toml, with at least mcp[cli] and defusedxml missing from the lock-style file. Source: pyproject.toml:1-40, Source: requirements.txt:1-30 When installing via requirements.txt, users should verify the file against pyproject.toml or prefer pip install . until the file is updated. Source: community discussion, issue #1

Design Observations

• Separation of concerns: Configuration, transport, providers, and tools each live in their own module boundary, which keeps the system testable and extensible to additional providers (e.g., other OpenAI-compatible APIs) by adding a new service module and registering it in model_registry.py. Source: app/services/model_registry.py:45-70
• Declarative tool surface: Tools are registered rather than hard-coded into the server, mirroring MCP's recommended pattern and enabling additive feature growth without touching transport code. Source: app/tools/registry.py:30-60
• Single config source: All provider credentials and runtime flags flow through app/core/config.py, reducing the risk of inconsistent environment handling across services. Source: app/core/config.py:35-75

Summary

omni-ai-mcp is a provider-agnostic MCP server whose architecture is organized around a clear layering: a server entry point, a centralized configuration module, provider-specific service adapters (Gemini, OpenRouter), and two registries — one for models, one for tools. This structure lets clients discover capabilities and invoke tools consistently regardless of the underlying provider. Developers extending the project should add new providers as new service modules and register them in model_registry.py, and add new MCP tools by registering handlers in tools/registry.py. Operators should be aware of the known requirements.txt drift issue and prefer pip install . or manually reconcile the file against pyproject.toml until the discrepancy is resolved.

Related Pages

Related topics: Repository Overview & System Architecture, Configuration, Installation & Deployment

Tools & Multi-Provider Model Routing

Purpose and Scope

The omni-ai-mcp project exposes its capabilities to MCP-compatible clients (such as Claude Desktop or other agent runtimes) through a collection of tools declared under app/tools/text/. Each tool is an individual unit of work that the host LLM can invoke with structured arguments. Several of these tools share a common shape: they accept a user prompt, optional conversation context, an optional system instruction, and delegate the actual generation step to an upstream AI provider. Because the upstream provider can vary, the project implements a multi-provider routing layer that normalizes how prompts reach different backends such as OpenAI-compatible APIs, Google's Gemini, and others. Source: app/tools/text/ask_model.py

The routing layer's job is to decouple *what the user wants done* from *which model actually does it*. A tool such as ask_model is a generic dispatcher: the caller names a provider and model, and the tool routes the request. A tool such as ask_gemini is a thin specialization that hard-codes the Gemini provider so the host LLM does not have to specify it. Higher-level tools such as brainstorm, challenge, code_review, and conversations reuse the same dispatch primitives to provide opinionated, task-specific prompts on top of the routing machinery. Source: app/tools/text/ask_gemini.py, app/tools/text/brainstorm.py

Tool Catalog and Provider Routing

The text tools are organized by verb rather than by provider. This separation matters: it means that adding a new provider does not require duplicating every tool, and adding a new tool does not require re-implementing provider SDK calls. The canonical routing entry point is ask_model, which accepts a provider identifier and delegates to the matching client implementation. Source: app/tools/text/ask_model.py

The table below summarizes the visible tool surface and the routing strategy each one uses:

ask_gemini exists alongside ask_model to give the host LLM a convenient shortcut when Gemini is the obvious choice, removing one argument from the call site. Source: app/tools/text/ask_gemini.py

The remaining four tools do not introduce new routing paths; they add prompt shaping and state management. brainstorm and challenge send engineered system instructions to encourage divergent or critical thinking respectively. code_review augments the dispatcher call with a structured code block plus a review-oriented system prompt. conversations is the only tool in this set that is explicitly stateful: it persists prior turns so the routed model has dialogue context. Source: app/tools/text/brainstorm.py, app/tools/text/challenge.py, app/tools/text/code_review.py, app/tools/text/conversations.py

Request Lifecycle

A typical call into the text-tool layer follows the same skeleton regardless of which tool the host LLM invoked:

1. The MCP host deserializes the tool arguments and validates them against the tool's input schema.
2. The tool module builds a payload consisting of a system prompt, the user's content, and any task-specific framing (for example, a "critique this" instruction for challenge).
3. The payload is handed to the routing function inside ask_model, which selects the provider client based on the provider argument.
4. The selected client performs the network call, returning a completion.
5. The tool formats the completion as an MCP tool response and returns it to the host.

Source: app/tools/text/ask_model.py, app/tools/text/brainstorm.py, app/tools/text/code_review.py

flowchart LR
    A[MCP Host] --> B[Tool Entry e.g. ask_model]
    B --> C{Provider Argument}
    C -->|openai| D[OpenAI Client]
    C -->|gemini| E[Gemini Client]
    C -->|anthropic| F[Anthropic Client]
    D --> G[Completion]
    E --> G
    F --> G
    G --> A

This pattern means tools like ask_gemini can be implemented as a thin adapter that simply calls ask_model with provider="gemini" pre-filled, instead of re-implementing the dispatch logic. Source: app/tools/text/ask_gemini.py

Extending the Routing Layer

Adding a new provider is a localized change. A developer adds a new branch inside the dispatcher in ask_model, supplies API key configuration through the project's settings layer, and every existing tool (brainstorm, challenge, code_review, conversations) immediately gains access to that provider without further code changes. Conversely, adding a new task-shaped tool is also localized: the developer composes the desired system prompt and forwards the call through the same dispatcher. Source: app/tools/text/ask_model.py, app/tools/text/code_review.py

Community reports indicate that installation issues can mask provider features because the dependency set must include both the MCP CLI shim and provider-specific parsers. For example, defusedxml is required to safely parse some provider responses, and mcp[cli] is required to expose the tool surface to MCP hosts at all. If either is missing, every tool in this routing layer will fail at import time rather than at call time, which can appear to be a routing bug. Source: [community context: issue #1 — requirements.txt missing dependencies (mcp[cli], defusedxml)]()

Operational Notes

• All tools in this layer are stateless from the caller's perspective except for conversations, which manages its own turn history. Source: app/tools/text/conversations.py
• Provider selection happens per call, not per session. A host can mix providers across successive tool invocations. Source: app/tools/text/ask_model.py
• Task-specific tools are deliberately thin wrappers, so behavior changes (such as new safety filters or new reasoning prompts) should be made in the dispatcher first and in the wrappers second. Source: app/tools/text/ask_gemini.py, app/tools/text/brainstorm.py
• Because the routing layer normalizes provider differences, swapping backends is a configuration change rather than a code change for any of the task-shaped tools. Source: app/tools/text/code_review.py

Related Pages

Related topics: Security, Persistence & Known Issues

Configuration, Installation & Deployment

The omni-ai-mcp project is packaged as a Python application that follows the standard Model Context Protocol (MCP) server conventions. Installation, configuration, and deployment are split across several entry points: a declarative packaging manifest (pyproject.toml), a pip-style dependency lock (requirements.txt), a shell bootstrap script (setup.sh), a Python launcher (run.py), and container manifests (Dockerfile, docker-compose.yml). This page documents how those files fit together and how to install, configure, and deploy the server.

Packaging & Dependency Management

The project ships two parallel dependency descriptors that are intended to remain in sync.

• pyproject.toml is the canonical source of dependencies and is used by pip install . and any PEP 517/518 compliant build frontend. It is the authoritative manifest.
• requirements.txt is provided for environments that prefer a flat dependency list and for direct pip install -r requirements.txt workflows.

Community-reported issue: The requirements.txt file has been reported out of sync with pyproject.toml. Specifically, mcp[cli] and defusedxml are declared in pyproject.toml but were missing from requirements.txt, causing installation failures when users relied on the flat file alone. When installing via requirements.txt, ensure both extras are present, or prefer pip install . (which reads pyproject.toml) until the file is corrected. Source: requirements.txt, pyproject.toml.

Source: pyproject.toml, requirements.txt.

Local Installation via `setup.sh`

setup.sh is a convenience bootstrap script that automates the local Python environment setup. It typically creates a virtual environment, upgrades pip, and installs dependencies from the canonical manifest. Source: setup.sh.

A typical invocation is:

chmod +x setup.sh
./setup.sh

After the script completes, the application is launched through run.py, which is the project's main entry point. Source: run.py. run.py is responsible for parsing environment-based configuration, instantiating the MCP server, and binding it to the chosen transport (commonly stdio for MCP clients).

Configuration

Configuration is environment-driven and follows the standard 12-factor pattern expected of MCP servers:

• API keys and secrets are read from environment variables rather than committed to source.
• Transport selection (stdio vs. SSE/HTTP) is selected at launch time via run.py arguments.
• Logging verbosity is typically controlled via standard LOG_LEVEL style variables.

Because the repository deliberately keeps secrets out of version control, contributors should populate a local .env file or pass variables inline when invoking run.py. The authoritative list of supported variables is defined by the imports and os.environ lookups inside run.py. Source: run.py.

Containerized Deployment

For reproducible production deployments, the project provides a Dockerfile and a docker-compose.yml.

flowchart LR
    A[docker-compose up] --> B[Build image from Dockerfile]
    B --> C[Install deps from pyproject.toml]
    C --> D[Launch run.py as container entrypoint]
    D --> E[MCP server ready]

• The Dockerfile pins a Python base image, copies the project files, and installs dependencies — usually by invoking pip install . against pyproject.toml, which avoids the requirements.txt drift problem entirely. Source: Dockerfile.
• docker-compose.yml orchestrates the container, exposes any required ports for HTTP/SSE transports, and injects environment variables for API keys and runtime configuration. Source: docker-compose.yml.

Typical usage:

docker compose up --build

This path is the recommended deployment flow because it bypasses the reported requirements.txt inconsistency by installing from pyproject.toml instead.

Summary

• Install locally with pip install . (preferred) or pip install -r requirements.txt after verifying the file includes mcp[cli] and defusedxml. Source: pyproject.toml, requirements.txt.
• Use setup.sh for an automated local bootstrap, then launch via run.py. Source: setup.sh, run.py.
• Use Dockerfile + docker-compose.yml for reproducible, secret-aware deployments. Source: Dockerfile, docker-compose.yml.
• All configuration is supplied via environment variables consumed by run.py. Source: run.py.

Related Pages

Related topics: Configuration, Installation & Deployment

Security, Persistence & Known Issues

Overview

This page consolidates three concerns that cut across the omni-ai-mcp codebase: how the application protects itself and its callers from malformed or hostile input, how state is persisted between MCP sessions, and the catalog of publicly tracked issues that affect reliability or installation. Together they describe the operational "edge" of the system — the parts a contributor or operator must understand before shipping a change.

The repository organizes these concerns into three areas of the source tree:

Source: app/core/security.py

Security

Input Validation

All incoming tool calls flow through Pydantic schemas defined in app/schemas/inputs.py before reaching any business logic. Schema-level constraints (length limits, regex patterns, allowed enums) are the first line of defense against malformed payloads and are the canonical place to look when extending the surface area of the MCP server.

Source: app/schemas/inputs.py

XML Hardening

The project intentionally depends on defusedxml instead of the standard library's xml/ElementTree modules. This is a deliberate mitigation against XML External Entity (XXE) and billion-laughs attacks, which are otherwise trivial to trigger when parsing untrusted XML inside an MCP tool. Centralizing this in app/core/security.py ensures every XML consumer in the codebase goes through the same hardened path.

Source: app/core/security.py

Persistence

Long-lived state — including chat history, indexed documents, and per-session configuration — is owned by the persistence service. app/services/persistence.py is the single module responsible for read/write paths, so any change to the on-disk layout or backend (file-based vs. database) should originate here.

The persistence layer is deliberately isolated from tool implementations: tools accept a persistence client through dependency injection rather than importing storage primitives directly. This keeps the security boundary clean and makes the layer easy to swap or mock during tests.

Source: app/services/persistence.py

Logging as an Audit Trail

app/core/logging.py configures structured logging that captures security-relevant events (validation rejections, XML parse failures) and persistence events (read/write errors, schema migrations). When investigating an incident, these logs are the recommended first stop because they correlate tool invocations with the modules that processed them.

Source: app/core/logging.py

Known Issues

Dependency Mismatch Between `requirements.txt` and `pyproject.toml`

The most prominent open issue in the tracker concerns the divergence between the two dependency manifests. pyproject.toml lists every runtime dependency the code actually imports, but requirements.txt is missing at least two entries that are required at runtime:

Source: pyproject.toml, requirements.txt

The practical effect is that contributors who follow the README and install with pip install -r requirements.txt will hit ModuleNotFoundError as soon as they invoke an XML-parsing tool or the CLI entry point, even though a pip install . (using pyproject.toml) would succeed. Until the manifests are reconciled, the recommended workaround is to install via pyproject.toml or to add the missing entries to requirements.txt manually.

This issue is tracked at https://github.com/marmyx77/omni-ai-mcp/issues/1 and is the canonical example of why requirements.txt and pyproject.toml must be kept in lockstep in this project.

Operational Guidance

When triaging new bugs in this area:

1. Confirm whether the failing module is listed in both pyproject.toml and requirements.txt; if not, the bug is likely a manifestation of the dependency-drift issue above.
2. Check app/core/logging.py output for the structured event type — persistence and security code paths are expected to emit distinct event tags.
3. For input-validation failures, reproduce against the schemas in app/schemas/inputs.py to determine whether the rejection is intended behavior or a missing constraint.

Source: app/core/security.py, app/services/persistence.py, app/core/logging.py, app/schemas/inputs.py, requirements.txt, pyproject.toml

Doramagic Pitfall Log

Found 8 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/marmyx77/omni-ai-mcp/issues/1

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/marmyx77/omni-ai-mcp

3. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/marmyx77/omni-ai-mcp

4. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/marmyx77/omni-ai-mcp

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/marmyx77/omni-ai-mcp

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/marmyx77/omni-ai-mcp

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/marmyx77/omni-ai-mcp

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/marmyx77/omni-ai-mcp

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using omni-ai-mcp with real data or production workflows.

• [Bug: requirements.txt missing dependencies (mcp[cli], defusedxml)](https://github.com/marmyx77/omni-ai-mcp/issues/1) - github / github_issue
• Configuration risk requires verification - GitHub / issue