# webexsamples/webex-messaging-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/webexsamples/webex-messaging-mcp-server
- Repository: https://github.com/webexsamples/webex-messaging-mcp-server

## Overview

1. This repository is a thin MCP adapter around the Cisco Webex Messaging REST API. Its job is to expose Webex operations as MCP tools so AI clients can create, read, update, and delete messaging resources without talking to Webex directly.

2. The main runtime entrypoint is `mcpServer.js`. It is the server process that wires the tool catalog into the Model Context Protocol and supports two transports: default STDIO for desktop-style MCP clients, and HTTP/StreamableHTTP for networked clients.

3. `index.js` is the CLI-facing entrypoint. The README shows it being used for tool listing and discovery, so the repo has a second execution path for inspection and automation separate from the long-running MCP server.

4. Tool implementation lives under `tools/webex-public-workspace/webex-messaging/`. Each file there corresponds to one Webex operation such as `create-a-message.js`, `list-rooms.js`, `create-a-webhook.js`, or `update-a-team.js`. Architecturally, these are the concrete adapters from MCP tool calls to Webex API requests.

5. `tools-manifest.json` is the catalog layer. It documents the available tools, their categories, environment requirements, and inventory metadata. That makes the repo self-describing and supports discovery, validation, and documentation generation.

6. `lib/tools.js`, `discover-tools.js`, `commands/tools.js`, and `tools/paths.js` form the tool-loading and discovery subsystem. Their role is to resolve which tool modules exist, expose them to the server, and support CLI/reporting workflows around the tool set.

7. `lib/webex-config.js` is the configuration boundary for outbound API access. It centralizes Webex base URL and authentication settings, keeping token handling out of the individual tool files and giving the rest of the code a single source of truth for API configuration.

8. The key data flow is: MCP client request → server/CLI → tool loader selects a tool module → tool module builds a Webex API call using configured credentials → Webex responds → result is returned back through MCP. There is no local database or message queue; the server is essentially stateless apart from request/session handling in HTTP mode.

9. The external system boundary is Cisco Webex itself. The repo depends on a Webex bearer token, and the tool implementations use HTTP `fetch` calls against the Webex API endpoint. The server is therefore an API gateway/integration layer rather than a business-logic application.

10. Transport behavior is operationally important: STDIO mode is the default for embedded MCP clients, while HTTP mode adds `/health` and `/mcp` endpoints plus session/CORS handling. This means the same tool layer is reused across both interactive and network deployments.

11. Deployment packaging is handled by `Dockerfile` and `docker-compose.yml`, with the repo designed for containerized execution. The README also indicates non-root container execution and environment-variable based secret injection, so deployment is intended to be ephemeral and configuration-driven.

12. `scripts/release.sh`, `.husky/pre-commit`, and the `.github` metadata indicate a small but formal release/quality pipeline. The repo treats tool correctness as critical, so validation is built around linting/quality checks and automated tests before commits or releases.

13. The test suite under `tests/` mirrors the architecture: there are dedicated suites for CLI behavior, MCP server behavior, Webex config, tool discovery, tool implementations, and end-to-end integration. That coverage shows the boundaries the project cares about most: configuration, loading, transport, and API-adapter correctness.

14. Overall, the architecture is a layered adapter: CLI/discovery layer on top, MCP transport/server layer in the middle, a centralized config and tool registry layer beneath that, and many one-file Webex operation adapters at the bottom. The only major external dependency is Webex Messaging, with the repo itself intentionally keeping no persistent state.

Main entry points: [`tests`](https://github.com/webexsamples/webex-messaging-mcp-server/tree/main/tests) (Test suite), [`mcpServer.js`](https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/mcpServer.js) (MCP server), [`lib/tools.js`](https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/lib/tools.js) (Tool loader), [`tools/webex-public-workspace/webex-messaging`](https://github.com/webexsamples/webex-messaging-mcp-server/tree/main/tools/webex-public-workspace/webex-messaging) (Webex ops)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entrypoints"]
  node_index_js["CLI entry<br/>[index.js]"]
  node_mcp_server_js["MCP server<br/>server entrypoint<br/>[mcpServer.js]"]
end

subgraph group_tooling["Tooling"]
  node_discover_tools_js["Discover tools<br/>discovery helper<br/>[discover-tools.js]"]
  node_commands_tools_js["Tools command<br/>cli command<br/>[tools.js]"]
  node_lib_tools_js["Tool loader<br/>loader/registry<br/>[tools.js]"]
  node_tools_manifest_json["Manifest<br/>catalog metadata"]
  node_tools_paths_js["Tool paths<br/>path registry<br/>[paths.js]"]
end

subgraph group_adapters["Webex adapters"]
  node_webex_messaging_dir["Webex ops<br/>tool adapters"]
end

subgraph group_integration["Integration boundary"]
  node_lib_webex_config_js["Webex config<br/>config boundary<br/>[webex-config.js]"]
  node_webex_api[("Webex API<br/>external service")]
end

subgraph group_ops["Ops"]
  node_dockerfile["Dockerfile<br/>container build"]
  node_docker_compose_yml["Compose<br/>deployment spec<br/>[docker-compose.yml]"]
  node_release_script["Release script<br/>release automation<br/>[release.sh]"]
  node_husky_precommit["Pre-commit<br/>quality hook<br/>[pre-commit]"]
  node_github_meta[".github<br/>repo metadata<br/>[.github]"]
end

subgraph group_tests["Tests"]
  node_tests_dir["Test suite<br/>test boundary"]
end

node_index_js -->|"uses"| node_discover_tools_js
node_index_js -->|"dispatches"| node_commands_tools_js
node_mcp_server_js -->|"loads"| node_lib_tools_js
node_mcp_server_js -->|"configures"| node_lib_webex_config_js
node_mcp_server_js -->|"advertises"| node_tools_manifest_json
node_discover_tools_js -->|"resolves"| node_tools_paths_js
node_commands_tools_js -->|"queries"| node_lib_tools_js
node_lib_tools_js -->|"maps"| node_tools_paths_js
node_lib_tools_js -->|"requires"| node_webex_messaging_dir
node_tools_manifest_json -.->|"documents"| node_webex_messaging_dir
node_webex_messaging_dir -->|"reads"| node_lib_webex_config_js
node_lib_webex_config_js -->|"targets"| node_webex_api
node_webex_messaging_dir -->|"calls"| node_webex_api
node_dockerfile -->|"runs"| node_mcp_server_js
node_docker_compose_yml -->|"builds"| node_dockerfile
node_release_script -->|"checks"| node_tests_dir
node_husky_precommit -->|"guards"| node_tests_dir
node_github_meta -.->|"coordinates"| node_release_script
node_tests_dir -.->|"covers"| node_mcp_server_js
node_tests_dir -.->|"covers"| node_lib_webex_config_js
node_tests_dir -.->|"covers"| node_lib_tools_js
node_tests_dir -.->|"covers"| node_webex_messaging_dir

click node_index_js "https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/index.js"
click node_mcp_server_js "https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/mcpServer.js"
click node_discover_tools_js "https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/discover-tools.js"
click node_commands_tools_js "https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/commands/tools.js"
click node_lib_tools_js "https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/lib/tools.js"
click node_tools_manifest_json "https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/tools-manifest.json"
click node_tools_paths_js "https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/tools/paths.js"
click node_webex_messaging_dir "https://github.com/webexsamples/webex-messaging-mcp-server/tree/main/tools/webex-public-workspace/webex-messaging"
click node_lib_webex_config_js "https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/lib/webex-config.js"
click node_dockerfile "https://github.com/webexsamples/webex-messaging-mcp-server/tree/main/Dockerfile"
click node_docker_compose_yml "https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/docker-compose.yml"
click node_release_script "https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/scripts/release.sh"
click node_husky_precommit "https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/.husky/pre-commit"
click node_tests_dir "https://github.com/webexsamples/webex-messaging-mcp-server/tree/main/tests"
click node_github_meta "https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/.github"

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_index_js,node_mcp_server_js toneBlue
class node_discover_tools_js,node_commands_tools_js,node_lib_tools_js,node_tools_manifest_json,node_tools_paths_js toneAmber
class node_webex_messaging_dir toneMint
class node_lib_webex_config_js,node_webex_api toneRose
class node_dockerfile,node_docker_compose_yml,node_release_script,node_husky_precommit,node_github_meta toneIndigo
class node_tests_dir toneTeal
```

## Components

### Entrypoints

CLI and long-running server entrypoints

- [CLI entry](https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/index.js): cli entrypoint · CLI-facing path for listing and discovery · `index.js`
- [MCP server](https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/mcpServer.js): server entrypoint · Main MCP runtime supporting STDIO and HTTP/StreamableHTTP · `mcpServer.js`

### Tooling

Tool catalog, loading, and discovery

- [Discover tools](https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/discover-tools.js): discovery helper · Enumerates available tools for inspection and automation · `discover-tools.js`
- [Tools command](https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/commands/tools.js): cli command · CLI command surface for tool listing and reporting · `commands/tools.js`
- [Tool loader](https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/lib/tools.js): loader/registry · Resolves, loads, and exposes tool modules · `lib/tools.js`
- [Manifest](https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/tools-manifest.json): catalog metadata · Self-describing inventory of tools and requirements · `tools-manifest.json`
- [Tool paths](https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/tools/paths.js): path registry · Central path helpers for tool resolution · `tools/paths.js`

### Webex adapters

Concrete MCP tool implementations for Webex Messaging

- [Webex ops](https://github.com/webexsamples/webex-messaging-mcp-server/tree/main/tools/webex-public-workspace/webex-messaging): tool adapters · One-file adapters for Webex Messaging operations · `tools/webex-public-workspace/webex-messaging`

### Integration boundary

Outbound Webex configuration and API boundary

- [Webex config](https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/lib/webex-config.js): config boundary · Centralizes endpoint and authentication settings · `lib/webex-config.js`
- **Webex API**: external service · Cisco Webex Messaging REST API boundary

### Ops

Packaging and release automation

- [Dockerfile](https://github.com/webexsamples/webex-messaging-mcp-server/tree/main/Dockerfile): container build · Container image definition for server execution · `Dockerfile`
- [Compose](https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/docker-compose.yml): deployment spec · Containerized runtime wiring and environment setup · `docker-compose.yml`
- [Release script](https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/scripts/release.sh): release automation · Automated release and publishing flow · `scripts/release.sh`
- [Pre-commit](https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/.husky/pre-commit): quality hook · Local commit gate for validation checks · `.husky/pre-commit`
- [.github](https://github.com/webexsamples/webex-messaging-mcp-server/blob/main/.github): repo metadata · Repository ownership and automation metadata · `.github`

### Tests

Repository coverage around the main boundaries

- [Test suite](https://github.com/webexsamples/webex-messaging-mcp-server/tree/main/tests): test boundary · Coverage for CLI, server, config, tools, and integration behavior · `tests`

## Connections

- CLI entry → Discover tools: uses · CLI discovery path relies on tool enumeration
- CLI entry → Tools command: dispatches · CLI entry routes tool-related commands
- MCP server → Tool loader: loads · Server wires the tool catalog into MCP
- MCP server → Webex config: configures · Server uses shared Webex credentials and base URL
- MCP server → Manifest: advertises · Server exposes the declared tool inventory
- Discover tools → Tool paths: resolves · Discovery uses shared tool path resolution
- Tools command → Tool loader: queries · CLI command reads the loaded tool set
- Tool loader → Tool paths: maps · Loader maps logical tools to filesystem locations
- Tool loader → Webex ops: requires · Loader imports individual Webex operation modules
- Manifest → Webex ops: documents · Manifest mirrors the available Webex tool surface
- Webex ops → Webex config: reads · Adapters use shared outbound configuration
- Webex config → Webex API: targets · Config points requests at the Webex API boundary
- Webex ops → Webex API: calls · Tool adapters issue Webex REST requests
- Dockerfile → MCP server: runs · Container image starts the MCP server
- Compose → Dockerfile: builds · Compose orchestrates the containerized deployment
- Release script → Test suite: checks · Release flow depends on validation before publishing
- Pre-commit → Test suite: guards · Pre-commit hook protects repository quality
- .github → Release script: coordinates · GitHub metadata supports release automation
- Test suite → MCP server: covers · Tests validate server behavior and transports
- Test suite → Webex config: covers · Tests validate configuration handling
- Test suite → Tool loader: covers · Tests validate tool loading and discovery
- Test suite → Webex ops: covers · Tests exercise representative Webex tool adapters