# mechantchulo/ripple-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/mechantchulo/ripple-mcp
- Repository: https://github.com/mechantchulo/ripple-mcp

## Overview

Ripple is an MCP server that gives IBM Bob structured access to project operations context. In the principal workflow, a developer asks Bob to investigate; Bob chooses Ripple tools, receives evidence from Git, CI, deployment data, service health, and project documentation, then correlates it and reports a diagnosis. Ripple also supports GitHub pull-request creation and status checks. The demo FastAPI service supplies a health endpoint. Tool behavior is documented in the README and registration is visible in `server/main.py`; some tool implementations and demo routes were not sampled, so uncertain internal wiring is omitted.

Main entry points: [`server/main.py`](https://github.com/mechantchulo/ripple-mcp/blob/main/server/main.py) (Ripple MCP), [`server/tools/ci_tools.py`](https://github.com/mechantchulo/ripple-mcp/blob/main/server/tools/ci_tools.py) (CI status), [`server/tools/github_tools.py`](https://github.com/mechantchulo/ripple-mcp/blob/main/server/tools/github_tools.py) (Pull request tools), [`server/tools/git_tools.py`](https://github.com/mechantchulo/ripple-mcp/blob/main/server/tools/git_tools.py) (Recent changes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP interface"]
  node_mcp["Ripple MCP<br/>[main.py]"]
end

subgraph group_evidence["Operational evidence"]
  node_git_tool["Recent changes<br/>[git_tools.py]"]
  node_ci_tool["CI status<br/>[ci_tools.py]"]
  node_deploy_tool["Deployment info"]
  node_health_tool["Service health<br/>[health_tools.py]"]
  node_docs_tool["Docs search<br/>[docs_tools.py]"]
  node_git_repo["Project Git repository"]
  node_github_actions["GitHub Actions"]
  node_ci_fixture["CI fixture<br/>[ci_status.json]"]
  node_deployment_fixture["Deployment fixture<br/>[deployment.json]"]
  node_project_docs["Project Markdown"]
end

subgraph group_changes["GitHub changes"]
  node_github_tools["Pull request tools<br/>[github_tools.py]"]
  node_github_api["GitHub REST API"]
end

subgraph group_demo["Demo service"]
  node_health_service["Demo health endpoint"]
  node_demo_app["FastAPI app<br/>[main.py]"]
  node_database_check["Database availability<br/>[database.py]"]
end

node_developer(("Developer"))
node_bob(("IBM Bob"))

node_developer -->|"asks"| node_bob
node_bob -->|"calls tools"| node_mcp
node_mcp -->|"dispatches"| node_git_tool
node_mcp -->|"dispatches"| node_ci_tool
node_mcp -->|"dispatches"| node_deploy_tool
node_mcp -->|"dispatches"| node_health_tool
node_mcp -->|"dispatches"| node_docs_tool
node_mcp -->|"dispatches"| node_github_tools
node_git_tool -->|"reads history"| node_git_repo
node_ci_tool -.->|"queries CI"| node_github_actions
node_ci_tool -->|"reads fallback"| node_ci_fixture
node_deploy_tool -->|"reads record"| node_deployment_fixture
node_docs_tool -->|"searches"| node_project_docs
node_health_tool -->|"checks health"| node_health_service
node_health_service -->|"serves route"| node_demo_app
node_demo_app -->|"checks availability"| node_database_check
node_github_tools -->|"creates or checks PR"| node_github_api
node_github_tools -->|"reads branch or remote"| node_git_repo
node_mcp -->|"returns evidence"| node_bob

click node_mcp "https://github.com/mechantchulo/ripple-mcp/blob/main/server/main.py"
click node_git_tool "https://github.com/mechantchulo/ripple-mcp/blob/main/server/tools/git_tools.py"
click node_ci_tool "https://github.com/mechantchulo/ripple-mcp/blob/main/server/tools/ci_tools.py"
click node_deploy_tool "https://github.com/mechantchulo/ripple-mcp/blob/main/server/tools/deployment_tools.py"
click node_health_tool "https://github.com/mechantchulo/ripple-mcp/blob/main/server/tools/health_tools.py"
click node_docs_tool "https://github.com/mechantchulo/ripple-mcp/blob/main/server/tools/docs_tools.py"
click node_ci_fixture "https://github.com/mechantchulo/ripple-mcp/blob/main/demo_data/ci_status.json"
click node_deployment_fixture "https://github.com/mechantchulo/ripple-mcp/blob/main/demo_data/deployment.json"
click node_project_docs "https://github.com/mechantchulo/ripple-mcp/tree/main/docs"
click node_health_service "https://github.com/mechantchulo/ripple-mcp/tree/main/demo_app/app/routes"
click node_demo_app "https://github.com/mechantchulo/ripple-mcp/blob/main/demo_app/app/main.py"
click node_database_check "https://github.com/mechantchulo/ripple-mcp/blob/main/demo_app/app/services/database.py"
click node_github_tools "https://github.com/mechantchulo/ripple-mcp/blob/main/server/tools/github_tools.py"

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_mcp toneBlue
class node_git_tool,node_ci_tool,node_deploy_tool,node_health_tool,node_docs_tool,node_git_repo,node_github_actions,node_ci_fixture,node_deployment_fixture,node_project_docs toneAmber
class node_github_tools,node_github_api toneMint
class node_health_service,node_demo_app,node_database_check toneRose
class node_developer,node_bob toneIndigo
```

## Components

### MCP interface

- [Ripple MCP](https://github.com/mechantchulo/ripple-mcp/blob/main/server/main.py): `server/main.py`

### Operational evidence

- [Recent changes](https://github.com/mechantchulo/ripple-mcp/blob/main/server/tools/git_tools.py): `server/tools/git_tools.py`
- [CI status](https://github.com/mechantchulo/ripple-mcp/blob/main/server/tools/ci_tools.py): `server/tools/ci_tools.py`
- [Deployment info](https://github.com/mechantchulo/ripple-mcp/blob/main/server/tools/deployment_tools.py): `server/tools/deployment_tools.py`
- [Service health](https://github.com/mechantchulo/ripple-mcp/blob/main/server/tools/health_tools.py): `server/tools/health_tools.py`
- [Docs search](https://github.com/mechantchulo/ripple-mcp/blob/main/server/tools/docs_tools.py): `server/tools/docs_tools.py`
- **Project Git repository**
- **GitHub Actions**
- [CI fixture](https://github.com/mechantchulo/ripple-mcp/blob/main/demo_data/ci_status.json): `demo_data/ci_status.json`
- [Deployment fixture](https://github.com/mechantchulo/ripple-mcp/blob/main/demo_data/deployment.json): `demo_data/deployment.json`
- [Project Markdown](https://github.com/mechantchulo/ripple-mcp/tree/main/docs): `docs`

### GitHub changes

- [Pull request tools](https://github.com/mechantchulo/ripple-mcp/blob/main/server/tools/github_tools.py): `server/tools/github_tools.py`
- **GitHub REST API**

### Demo service

- [Demo health endpoint](https://github.com/mechantchulo/ripple-mcp/tree/main/demo_app/app/routes): `demo_app/app/routes`
- [FastAPI app](https://github.com/mechantchulo/ripple-mcp/blob/main/demo_app/app/main.py): `demo_app/app/main.py`
- [Database availability](https://github.com/mechantchulo/ripple-mcp/blob/main/demo_app/app/services/database.py): `demo_app/app/services/database.py`

### Other components

- **Developer**
- **IBM Bob**

## Connections

- Developer → IBM Bob: asks
- IBM Bob → Ripple MCP: calls tools
- Ripple MCP → Recent changes: dispatches
- Ripple MCP → CI status: dispatches
- Ripple MCP → Deployment info: dispatches
- Ripple MCP → Service health: dispatches
- Ripple MCP → Docs search: dispatches
- Ripple MCP → Pull request tools: dispatches
- Recent changes → Project Git repository: reads history
- CI status → GitHub Actions: queries CI
- CI status → CI fixture: reads fallback
- Deployment info → Deployment fixture: reads record
- Docs search → Project Markdown: searches
- Service health → Demo health endpoint: checks health
- Demo health endpoint → FastAPI app: serves route
- FastAPI app → Database availability: checks availability
- Pull request tools → GitHub REST API: creates or checks PR
- Pull request tools → Project Git repository: reads branch or remote
- Ripple MCP → IBM Bob: returns evidence