guile-changeflow by dsp-dr - MCP Server

#+TITLE: ChangeFlow - ITIL 4 Change Management System #+STARTUP: overview

[[./assets/banner.png]]

[[https://github.com/dsp-dr/guile-changeflow/actions/workflows/ci.yml][https://github.com/dsp-dr/guile-changeflow/actions/workflows/ci.yml/badge.svg]] [[https://github.com/dsp-dr/guile-changeflow/releases][https://img.shields.io/github/v/release/dsp-dr/guile-changeflow.svg?include_prereleases]] [[https://mcp.changeflow.us][https://img.shields.io/badge/deployed-Cloudflare%20Workers-orange.svg]] [[LICENSE][https://img.shields.io/badge/license-MIT-blue.svg]]

Overview

ChangeFlow is a comprehensive ITIL 4 compliant change management system designed for enterprise IT operations. It provides automated risk assessment, approval workflows, and AI-powered change tracking through the Model Context Protocol (MCP).

Key Features

** ITIL 4 Compliance

Full change lifecycle management (RFC to implementation)
CAB (Change Advisory Board) approval workflows
Risk assessment and impact analysis
Emergency change procedures
Standard change catalog
Audit trail and compliance reporting

** Automated Risk Assessment

Real-time risk scoring based on change attributes
Freeze period enforcement
Dependency tracking
Rollback planning
Impact analysis on affected systems

** MCP Integration The system exposes 8 ITIL-compliant tools via JSON-RPC 2.0:

=create_change_request= - Submit new RFCs with auto risk assessment
=get_change_request= - Query change information by ID
=list_change_requests= - Dashboard views with filtering
=assess_risk= - Automated risk scoring for proposed changes
=check_freeze_period= - Verify if date is in change freeze
=get_approval_status= - Check CAB approval progress
=emergency_override= - Break-glass procedures with audit
=audit_trail= - View change history and compliance logs

Testing

** Cloudflare AI Playground Test the MCP server using the Cloudflare AI Playground:

Visit [[https://playground.ai.cloudflare.com/][playground.ai.cloudflare.com]]
In the MCP Server URL field, enter: =https://mcp.changeflow.us/v1/sse=
Authenticate via GitHub OAuth at =https://mcp.changeflow.us/authorize=
The playground will automatically discover all 8 ITIL tools
Try commands like:
- "Create a change request for database upgrade"
- "Check if December 25th is in a freeze period"
- "Show the audit trail"

** MCP Inspector For detailed testing with the MCP Inspector: #+BEGIN_SRC bash npx @modelcontextprotocol/inspector@latest

Connect to: https://mcp.changeflow.us/v1/sse

#+END_SRC

Quick Start

** For Claude.ai Users

Authorize: Visit https://mcp.changeflow.us/authorize
Add to Claude: Settings → Custom Connectors → Add =https://mcp.changeflow.us/v1/sse=
Start Using: Access ITIL 4 change management tools directly in Claude

Troubleshooting: See [[docs/CLAUDE-AI-MCP-INTEGRATION.md][Claude.ai Integration Guide]] and [[docs/MCP-SEQUENCE-DIAGRAMS.md][Sequence Diagrams]]

** Production API #+BEGIN_SRC bash

Check system status

curl https://mcp.changeflow.us/health

List available MCP tools (requires OAuth)

curl -X POST https://mcp.changeflow.us/v1/sse
-H "Content-Type: application/json"
-H "Authorization: Bearer YOUR_TOKEN"
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}' #+END_SRC

** Local Development #+BEGIN_SRC bash

Clone repository

git clone https://github.com/dsp-dr/guile-changeflow.git cd guile-changeflow

Start MCP server (auto-starts on port 8427 with direnv)

node scripts/mcp-local-server.js

Run test suite

node test/mcp-comprehensive-test.js #+END_SRC

** Deploy Your Own Instance #+BEGIN_SRC bash

Configure Cloudflare credentials

cp .env.example .env

Edit .env with your CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID

Deploy to Cloudflare Workers

cd infra/cloudflare wrangler publish #+END_SRC

Usage Examples

** Creating a Change Request #+BEGIN_SRC json { "jsonrpc": "2.0", "method": "create_change_request", "params": { "title": "Database Schema Update", "description": "Add authentication fields to user table", "category": "normal", "priority": "medium", "impact": "medium", "risk_score": 45, "scheduled_start": "2025-09-20T10:00:00Z", "scheduled_end": "2025-09-20T12:00:00Z" }, "id": 1 } #+END_SRC

** Assessing Risk #+BEGIN_SRC json { "jsonrpc": "2.0", "method": "assess_risk", "params": { "change_id": "CHG-20250914-0001", "factors": ["production", "database", "authentication"] }, "id": 2 } #+END_SRC

System Architecture

** Components

Web Dashboard: Executive view with real-time metrics
MCP Server: AI agent integration layer
Risk Engine: Automated assessment and scoring
State Machine: ITIL-compliant workflow engine
Database: SQLite with full audit trails

** State Workflow #+BEGIN_SRC submitted → assessing → approved → implementing → completed ↘ rejected ↓ ↗ ↘ needs-info → failed ─── ↘ cancelled #+END_SRC

Risk Assessment Model

** Change Types (ITIL 4)

| Type | Risk Threshold | Approval | Use Case | |-----------+----------------+-----------+-----------------| | Standard | < 30 | Automatic | Routine updates | | Normal | 30-70 | Required | Most changes | | Emergency | > 70 | Expedited | Critical fixes |

** Risk Factors

| Factor | Weight | Description | |-------------------------+--------+---------------------------------------| | Production impact | 30 | Changes affecting production systems | | Data modifications | 25 | Database schema or data changes | | Security implications | 20 | Authentication, authorization changes | | Multi-system changes | 15 | Cross-system dependencies | | Historical success rate | 10 | Past performance of similar changes |

Development Setup

** Prerequisites

GNU Guile 3.0+ (for local development)
Node.js 18+ (for MCP server)
Cloudflare Workers account (for deployment)
Make (for build automation)

** Quick Start #+BEGIN_SRC bash

Clone and setup

git clone https://github.com/dsp-dr/guile-changeflow.git cd guile-changeflow

Environment setup (automatic with direnv)

cp .env.example .env direnv allow

Run tests

make test

Start local MCP server

make mcp-server

Deploy to Cloudflare

make deploy #+END_SRC

Project Documentation

** Core Documents

| Document | Purpose | Location | |-------------------+-----------------------------------------+-------------------------------| | Setup & Build | Build system and tooling configuration | [[file:docs/setup.org][docs/setup.org]] | | System Design | Architecture and data models | [[file:docs/architecture/][docs/architecture/]] | | ITIL Requirements | ITIL 4 mapping and compliance | [[file:docs/itil-requirements.org][docs/itil-requirements.org]] | | MCP Protocol | Protocol implementation guide | [[file:docs/mcp-protocol.org][docs/mcp-protocol.org]] | | Deployment | Infrastructure and scaling strategy | [[file:docs/deployment.org][docs/deployment.org]] | | Roadmap v2.0 | Future development plans | [[file:docs/roadmap/V2.0-ROADMAP.org][docs/roadmap/V2.0-ROADMAP.org]] |

** Testing

*** Test Coverage Areas

Unit tests: Models and state machine
Integration tests: MCP protocol
System tests: End-to-end workflows
Performance tests: Bulk operations

*** Running Tests #+BEGIN_SRC bash

All tests

make test

Specific test suites

guile test/test-core-models.scm node test/mcp-comprehensive-test.js ./scripts/test-endpoints.sh #+END_SRC

Deployment

** Environments | Environment | URL | Purpose | |-------------+-----------------------------------------------------------+-------------| | Production | https://mcp.changeflow.us | Live system | | Staging | https://guile-changeflow-staging.jasonwalsh.workers.dev | Testing env | | Local | http://localhost:8427 | Development |

** CI/CD Pipeline

GitHub Actions for testing
Automatic deployment on main branch
Release tagging and versioning

Contributing

See [[file:CONTRIBUTING.org][CONTRIBUTING.org]] for:

Code style guidelines
Commit message format
Pull request process
Testing requirements

License

MIT License - See [[file:LICENSE][LICENSE]] for details

Support

Issues: [[https://github.com/dsp-dr/guile-changeflow/issues][GitHub Issues]]
Documentation: [[file:docs/][docs/ directory]]
API Reference: [[https://api.changeflow.us/docs][Online Documentation]]