# combodo/itop-mcp architecture

> Architecture diagram of the GitHub repository combodo/itop-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/combodo/itop-mcp
- Repository: https://github.com/combodo/itop-mcp

## Overview

itop-mcp is a Symfony-based MCP server that exposes iTop operations to an AI agent and communicates with iTop through its REST/JSON webservices. The main workflow is an agent invoking an MCP tool, which prepares a request and delegates to the iTop client; the client authenticates the REST call with the configured token, and the tool formats the response. Separate capabilities cover object reads/search, creation, updates, state stimuli, related-object lookup, and schema discovery. Source excerpts and the SOURCE INDEX support the tool and client links; unsampled Symfony wiring is not assumed.

Main entry points: [`src/Tools/iTopRestTools.php`](https://github.com/combodo/itop-mcp/blob/master/src/Tools/iTopRestTools.php) (Request Formatter), [`src/Service/DatamodelService.php`](https://github.com/combodo/itop-mcp/blob/master/src/Service/DatamodelService.php) (Datamodel Service), [`src/Capability/iTopBuilder.php`](https://github.com/combodo/itop-mcp/blob/master/src/Capability/iTopBuilder.php) (Capability Builder), [`src/Service/iTopClient.php`](https://github.com/combodo/itop-mcp/blob/master/src/Service/iTopClient.php) (REST Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP Server"]
  node_builder["Capability Builder<br/>[iTopBuilder.php]"]
  node_home["Setup Status Page<br/>[HomeController.php]"]
end

subgraph group_tools["iTop Tools"]
  node_read["Read &amp; Search<br/>[iTopGetTools.php]"]
  node_create["Create Objects"]
  node_update["Update Objects"]
  node_stimulus["Apply Stimulus"]
  node_related["Related Objects"]
  node_nlsearch["Natural Search"]
  node_templates["Request Formatter<br/>[iTopRestTools.php]"]
end

subgraph group_model["Datamodel"]
  node_schema["Schema Discovery"]
  node_datamodel["Datamodel Service"]
end

subgraph group_connection["iTop Connection"]
  node_interface["iTop Client Interface"]
  node_client["REST Client<br/>[iTopClient.php]"]
  node_user["Token User<br/>[User.php]"]
end

node_agent(("AI Agent"))
node_itop{{"iTop REST Service"}}

node_agent -.->|"uses MCP server"| node_builder
node_builder -->|"scans tools"| node_schema
node_read -->|"formats requests"| node_templates
node_create -->|"formats requests"| node_templates
node_update -->|"formats requests"| node_templates
node_stimulus -->|"formats requests"| node_templates
node_related -->|"formats requests"| node_templates
node_nlsearch -->|"formats requests"| node_templates
node_read -->|"reads schema"| node_datamodel
node_update -->|"reads schema"| node_datamodel
node_stimulus -->|"reads schema"| node_datamodel
node_related -->|"reads schema"| node_datamodel
node_schema -->|"queries schema"| node_datamodel
node_templates -->|"sends request via"| node_interface
node_builder -->|"checks connection"| node_interface
node_client -->|"gets token from"| node_user
node_client -->|"POSTs REST request"| node_itop
node_home -->|"checks endpoint"| node_client

click node_builder "https://github.com/combodo/itop-mcp/blob/master/src/Capability/iTopBuilder.php"
click node_read "https://github.com/combodo/itop-mcp/blob/master/src/Tools/core/get/iTopGetTools.php"
click node_create "https://github.com/combodo/itop-mcp/blob/master/src/Tools/core/create/iTopCreateTools.php"
click node_update "https://github.com/combodo/itop-mcp/blob/master/src/Tools/core/update/iTopUpdateTools.php"
click node_stimulus "https://github.com/combodo/itop-mcp/blob/master/src/Tools/core/apply_stimulus/iTopApplyStimulusTools.php"
click node_related "https://github.com/combodo/itop-mcp/blob/master/src/Tools/core/get_related/iTopGetRelatedTools.php"
click node_nlsearch "https://github.com/combodo/itop-mcp/blob/master/src/Tools/core/natural_language_search/iTopNaturalLanguageSearchTool.php"
click node_schema "https://github.com/combodo/itop-mcp/blob/master/src/Tools/schema/iTopSchemaTools.php"
click node_datamodel "https://github.com/combodo/itop-mcp/blob/master/src/Service/DatamodelService.php"
click node_templates "https://github.com/combodo/itop-mcp/blob/master/src/Tools/iTopRestTools.php"
click node_interface "https://github.com/combodo/itop-mcp/blob/master/src/Service/iTopClientInterface.php"
click node_client "https://github.com/combodo/itop-mcp/blob/master/src/Service/iTopClient.php"
click node_user "https://github.com/combodo/itop-mcp/blob/master/src/Security/User.php"
click node_home "https://github.com/combodo/itop-mcp/blob/master/src/Controller/HomeController.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_builder,node_home toneBlue
class node_read,node_create,node_update,node_stimulus,node_related,node_nlsearch,node_templates toneAmber
class node_schema,node_datamodel toneMint
class node_interface,node_client,node_user toneRose
class node_agent,node_itop toneIndigo
```

## Components

### MCP Server

- [Capability Builder](https://github.com/combodo/itop-mcp/blob/master/src/Capability/iTopBuilder.php): `src/Capability/iTopBuilder.php`
- [Setup Status Page](https://github.com/combodo/itop-mcp/blob/master/src/Controller/HomeController.php): `src/Controller/HomeController.php`

### iTop Tools

- [Read & Search](https://github.com/combodo/itop-mcp/blob/master/src/Tools/core/get/iTopGetTools.php): `src/Tools/core/get/iTopGetTools.php`
- [Create Objects](https://github.com/combodo/itop-mcp/blob/master/src/Tools/core/create/iTopCreateTools.php): `src/Tools/core/create/iTopCreateTools.php`
- [Update Objects](https://github.com/combodo/itop-mcp/blob/master/src/Tools/core/update/iTopUpdateTools.php): `src/Tools/core/update/iTopUpdateTools.php`
- [Apply Stimulus](https://github.com/combodo/itop-mcp/blob/master/src/Tools/core/apply_stimulus/iTopApplyStimulusTools.php): `src/Tools/core/apply_stimulus/iTopApplyStimulusTools.php`
- [Related Objects](https://github.com/combodo/itop-mcp/blob/master/src/Tools/core/get_related/iTopGetRelatedTools.php): `src/Tools/core/get_related/iTopGetRelatedTools.php`
- [Natural Search](https://github.com/combodo/itop-mcp/blob/master/src/Tools/core/natural_language_search/iTopNaturalLanguageSearchTool.php): `src/Tools/core/natural_language_search/iTopNaturalLanguageSearchTool.php`
- [Request Formatter](https://github.com/combodo/itop-mcp/blob/master/src/Tools/iTopRestTools.php): `src/Tools/iTopRestTools.php`

### Datamodel

- [Schema Discovery](https://github.com/combodo/itop-mcp/blob/master/src/Tools/schema/iTopSchemaTools.php): `src/Tools/schema/iTopSchemaTools.php`
- [Datamodel Service](https://github.com/combodo/itop-mcp/blob/master/src/Service/DatamodelService.php): `src/Service/DatamodelService.php`

### iTop Connection

- [iTop Client Interface](https://github.com/combodo/itop-mcp/blob/master/src/Service/iTopClientInterface.php): `src/Service/iTopClientInterface.php`
- [REST Client](https://github.com/combodo/itop-mcp/blob/master/src/Service/iTopClient.php): `src/Service/iTopClient.php`
- [Token User](https://github.com/combodo/itop-mcp/blob/master/src/Security/User.php): `src/Security/User.php`

### Other components

- **AI Agent**
- **iTop REST Service**

## Connections

- AI Agent → Capability Builder: uses MCP server (evidence: `README.md`)
- Capability Builder → Schema Discovery: scans tools (evidence: `src/Capability/iTopBuilder.php`)
- Read & Search → Request Formatter: formats requests (evidence: `src/Tools/core/get/iTopGetTools.php`)
- Create Objects → Request Formatter: formats requests (evidence: `src/Tools/core/create/iTopCreateTools.php`)
- Update Objects → Request Formatter: formats requests (evidence: `src/Tools/core/update/iTopUpdateTools.php`)
- Apply Stimulus → Request Formatter: formats requests (evidence: `src/Tools/core/apply_stimulus/iTopApplyStimulusTools.php`)
- Related Objects → Request Formatter: formats requests (evidence: `src/Tools/core/get_related/iTopGetRelatedTools.php`)
- Natural Search → Request Formatter: formats requests (evidence: `src/Tools/core/natural_language_search/iTopNaturalLanguageSearchTool.php`)
- Read & Search → Datamodel Service: reads schema (evidence: `src/Tools/core/get/iTopGetTools.php`)
- Update Objects → Datamodel Service: reads schema (evidence: `src/Tools/core/update/iTopUpdateTools.php`)
- Apply Stimulus → Datamodel Service: reads schema (evidence: `src/Tools/core/apply_stimulus/iTopApplyStimulusTools.php`)
- Related Objects → Datamodel Service: reads schema (evidence: `src/Tools/core/get_related/iTopGetRelatedTools.php`)
- Schema Discovery → Datamodel Service: queries schema (evidence: `src/Tools/schema/iTopSchemaTools.php`)
- Request Formatter → iTop Client Interface: sends request via (evidence: `src/Tools/iTopRestTools.php`)
- Capability Builder → iTop Client Interface: checks connection (evidence: `src/Capability/iTopBuilder.php`)
- REST Client → Token User: gets token from (evidence: `src/Service/iTopClient.php`)
- REST Client → iTop REST Service: POSTs REST request (evidence: `src/Service/iTopClient.php`)
- Setup Status Page → REST Client: checks endpoint (evidence: `src/Controller/HomeController.php`)
