# 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

```text
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:

```bash
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`.