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.

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.