Skip to main content
Glama
anielk

Cloudivo MCP

by anielk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Cloudivo MCP

Cloudivo MCP is the Model Context Protocol server that will act as the AI gateway for the Cloudivo ecosystem. It exposes MCP tools, resources, and prompts while delegating business behavior to downstream Cloudivo services.

Vision

The long-term goal is a production-ready MCP server that gives AI clients a consistent interface to Cloudivo capabilities without embedding business logic in the gateway itself.

  • MCP owns orchestration, registration, authentication, and protocol boundaries.

  • Services own business rules.

  • Clients own outbound API communication.

Related MCP server: AIPOLabs MCP Server

Architecture Overview

The application follows a strict layered flow:

Tool -> Service -> Client -> REST API

Bootstrap is intentionally small and modular:

  1. src/index.ts orchestrates startup.

  2. src/server/createServer.ts creates the MCP server.

  3. src/server/toolRegistry.ts registers tools.

  4. src/server/resourceRegistry.ts registers resources.

  5. src/server/promptRegistry.ts registers prompts.

  6. src/server/startServer.ts attaches transport and starts the process.

See docs/ARCHITECTURE.md for the detailed architecture reference.

Folder Structure

src/
  clients/       External API clients
  config/        Centralized runtime configuration
  prompts/       MCP prompt definitions
  resources/     MCP resource definitions
  server/        Bootstrap and registry modules
  services/      Business-facing orchestration without transport concerns
  tools/         MCP tool registration modules
  types/         Shared application types
  utils/         Small cross-cutting helpers only
tests/           Unit and registry tests
docs/            Project documentation

See docs/PROJECT_STRUCTURE.md for folder responsibility guidance.

Development Workflow

  1. Install dependencies with npm install.

  2. Start local development with npm run dev.

  3. Build the project with npm run build.

  4. Run the test suite with npm run test:run.

  5. Validate TypeScript without emitting files with npm run typecheck.

When adding new MCP functionality, keep src/index.ts unchanged and register new surfaces through the appropriate registry module.

Build Instructions

Prerequisites:

  • Node.js 22 LTS

  • npm 10+

Commands:

npm install
npm run build
npm start

The build emits compiled output to dist/.

Testing

Vitest is used for unit and registry tests.

  • npm test runs Vitest in the default mode.

  • npm run test:run runs the suite once.

  • npm run typecheck validates types without generating build output.

See docs/TESTING.md for the test strategy and roadmap.

Documentation

Core project references:

  • docs/ARCHITECTURE.md

  • docs/adr/README.md

  • docs/PROJECT_STRUCTURE.md

  • docs/DEVELOPMENT_GUIDE.md

  • docs/CODING_STANDARDS.md

  • docs/TESTING.md

  • docs/ENGINEERING_PRINCIPLES.md

  • docs/DEFINITION_OF_DONE.md

  • docs/SECURITY.md

  • docs/OPERATIONS.md

  • docs/adr/

Roadmap

Near-term priorities:

  • Harden configuration, logging, and error handling.

  • Add service and client foundations for external Cloudivo systems.

  • Expand test coverage across registries, services, and future clients.

See docs/ROADMAP.md for the phased plan.

Future Integrations

  • CTE

  • MailAPI

  • Leinaflow

  • Future Cloudivo services

Each integration will follow the same layering rules and will be introduced through dedicated client and service modules.

The first reusable integration boundary is the CTE client in src/clients/cte/CteClient.ts.

Available Tools

2 tools
system.healthSystem HealthA

Returns the current status of the Cloudivo MCP Server.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
statusYes
serviceYes
versionYes

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden for behavioral disclosure. It states the tool returns status, implicitly indicating a read-only operation, but it does not mention potential side effects, failure modes, or authentication requirements. This is minimal but not misleading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no redundant words. It directly states the purpose without any extraneous content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, output schema present), the description sufficiently covers its purpose. The output schema handles return-value details, so the description does not need to elaborate further.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and an empty input schema, so the description adds no parameter details. The zero-parameter baseline is 4, and no additional explanation is needed beyond what the empty schema already conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb ('Returns') and resource ('current status of the Cloudivo MCP Server'). It distinguishes itself from the sibling tool ticket.create by focusing on server health rather than ticket operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance is provided on when to use this tool versus alternatives. The use case (checking server health) is implied by the name and description, but there is no direct statement of when to choose this over ticket.create.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ticket.createCreate TicketC

Creates a ticket in the Cloudivo Ticket Engine.

ParametersJSON Schema
NameRequiredDescriptionDefault
tagsNo
titleYes
sourceYes
productYes
categoryYes
priorityNo
reporterYes
descriptionYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
urlYes
successYes
ticketIdYes
ticketNumberYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'Creates a ticket' without mentioning side effects, return behavior, authentication, validation, or error handling. This is insufficient for a create operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, direct sentence that communicates the core purpose with no wasted words. It is appropriately concise for the simple action it describes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema and a clear name, the description is too sparse for a tool with 8 parameters and no annotations. It lacks essential context about required fields, parameter meanings, and expected behavior, making it incomplete for an agent to reliably use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not mention any parameters or their meanings. The tool has 8 parameters (6 required), but the description adds no semantic value to help an agent understand how to populate them correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Creates a ticket') and the specific resource ('Cloudivo Ticket Engine'). It distinguishes itself from the only sibling tool (system.health) by being explicitly about ticket creation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, or any context about prerequisites or exclusions. The only sibling tool (system.health) is unrelated, but no usage direction is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedsystem.health
    • First observedticket.create
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.1/5.0

Scored across 2 tools

Disambiguation5/5

The two tools are completely distinct: one checks server health, the other creates tickets. There is no overlap or ambiguity between them.

Naming Consistency2/5

The naming pattern is inconsistent: 'system.health' uses a noun, while 'ticket.create' uses a verb. While both use dot notation, the verb/noun mismatch makes the naming style confusing.

Tool Count2/5

With only 2 tools for a server that includes a ticket engine, the tool set feels too thin. A ticket engine typically needs more operations, and the server's purpose appears underestimated.

Completeness2/5

The tool surface is severely limited: only ticket creation is supported, with no listing, retrieval, or update/delete operations for tickets. The system.health tool is fine but doesn't contribute to a complete workflow.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • AIPOLabs MCP Server

    aipotheosis-labs
    A
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol server that provides access to ACI.dev functions (tools) through either direct app-specific tools or a unified interface with dynamic tool discovery and execution based on user intent.
    253
    MIT
  • Apideck MCP by apideck-libraries

    Apideck MCPofficial

    apideck-libraries
    A
    license
    A
    quality
    A
    maintenance
    Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
    4
    223
    17
    MIT