ISPW MCP Server

A Model Context Protocol (MCP) server for BMC Compuware ISPW (Interactive Source Program Workbench) - a comprehensive source code management, release automation, and deployment automation tool for mainframe DevOps.

Overview

This MCP server enables LLMs to interact with ISPW through a comprehensive set of tools for:

• Assignment Management: Create, list, and retrieve assignments (containers for development work)
• Task Management: View tasks within assignments (individual modules/components)
• Release Management: Create and manage releases for coordinated deployments
• Operations: Generate, promote, and deploy code through the development lifecycle
• Set & Package Management: List and view deployment sets and packages

Features

• ✅ Complete ISPW REST API coverage for core workflows
• ✅ Token-based authentication with CES (Compuware Enterprise Services)
• ✅ Dual output formats: Human-readable Markdown and machine-readable JSON
• ✅ Comprehensive error handling with actionable messages
• ✅ Pydantic validation for all inputs
• ✅ Async/await for optimal performance
• ✅ Support for both production and custom CES servers

Installation

Prerequisites

• Python 3.10 or higher
• Access to a BMC Compuware ISPW instance
• Personal Access Token for CES authentication

Setup

1. Clone or create the project directory:

   cd /path/to/ispw-mcp-server
   

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -e .
   

4. Configure environment variables:

   cp .env.example .env
   

   Edit .env and set your values:

   # For custom CES server:
   CES_HOST=your-ces-host.example.com
   CES_PORT=2020
   
   # Or for production server:
   # ISPW_BASE_URL=https://ispw.api.compuware.com
   
   # Required: Your personal access token
   ISPW_API_TOKEN=your_token_here
   
   # Default SRID (optional, defaults to "ISPW")
   ISPW_DEFAULT_SRID=ISPW
   

Usage

Running the Server

As a standalone script:

python ispw_mcp_server.py

Using the installed command:

ispw-mcp-server

With the MCP Inspector (for testing):

npx @modelcontextprotocol/inspector python ispw_mcp_server.py

Configuration in Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ispw": {
      "command": "python",
      "args": ["/path/to/ispw-mcp-server/ispw_mcp_server.py"],
      "env": {
        "ISPW_BASE_URL": "https://your-ces-host:2020",
        "ISPW_API_TOKEN": "your_token_here",
        "ISPW_DEFAULT_SRID": "ISPW"
      }
    }
  }
}

Or using a virtual environment:

{
  "mcpServers": {
    "ispw": {
      "command": "/path/to/ispw-mcp-server/venv/bin/python",
      "args": ["/path/to/ispw-mcp-server/ispw_mcp_server.py"],
      "env": {
        "ISPW_BASE_URL": "https://your-ces-host:2020",
        "ISPW_API_TOKEN": "your_token_here",
        "ISPW_DEFAULT_SRID": "ISPW"
      }
    }
  }
}

Available Tools

Assignment Tools

ispw_list_assignments

List all assignments for a specific SRID, with optional filtering by level or assignment ID.

Parameters:

• srid (str): System Resource Identifier (default: from env)
• level (optional): Filter by level (DEV, INT, ACC, PRD)
• assignment_id (optional): Filter by specific assignment ID
• response_format (optional): "markdown" or "json" (default: markdown)

Example:

List all DEV level assignments for SRID ISPW

ispw_get_assignment

Get detailed information about a specific assignment.

Parameters:

• srid (str): System Resource Identifier
• assignment_id (str): Assignment identifier
• response_format (optional): Output format

Example:

Get details for assignment PLAY000001 in ISPW

ispw_create_assignment

Create a new assignment.

Parameters:

• srid (str): System Resource Identifier
• assignment_id (str): Unique assignment identifier
• stream (str): Stream name
• application (str): Application name
• description (optional): Assignment description
• default_path (optional): Default path
• response_format (optional): Output format

Example:

Create a new assignment PLAY000002 in ISPW for stream PLAY and application PLAY

Task Tools

ispw_list_tasks

List all tasks for a specific assignment.

Parameters:

• srid (str): System Resource Identifier
• assignment_id (str): Assignment identifier
• response_format (optional): Output format

Example:

List all tasks for assignment PLAY000001

Release Tools

ispw_list_releases

List all releases for a specific SRID.

Parameters:

• srid (str): System Resource Identifier
• release_id (optional): Filter by specific release ID
• response_format (optional): Output format

Example:

List all releases for ISPW

ispw_get_release

Get detailed information about a specific release.

Parameters:

• srid (str): System Resource Identifier
• release_id (str): Release identifier
• response_format (optional): Output format

ispw_create_release

Create a new release.

Parameters:

• srid (str): System Resource Identifier
• release_id (str): Unique release identifier
• stream (str): Stream name
• application (str): Application name
• description (optional): Release description
• response_format (optional): Output format

Operation Tools

ispw_generate_assignment

Generate code for an assignment (compile and prepare).

Parameters:

• srid (str): System Resource Identifier
• assignment_id (str): Assignment identifier
• level (optional): Target level for generation
• runtime_configuration (optional): Runtime configuration
• response_format (optional): Output format

Example:

Generate assignment PLAY000001 for level DEV

ispw_promote_assignment

Promote an assignment to the next level.

Parameters:

• srid (str): System Resource Identifier
• assignment_id (str): Assignment identifier
• level (optional): Target level for promotion
• change_type (optional): S (Standard), I (Incidental), E (Emergency)
• execution_status (optional): Execution status
• response_format (optional): Output format

Example:

Promote assignment PLAY000001 to INT level with Standard change type

ispw_deploy

Deploy an assignment, release, or set to target environment.

⚠️ CAUTION: This is a destructive operation that affects production or target environments.

Parameters:

• srid (str): System Resource Identifier
• target_id (str): Assignment, release, or set identifier
• target_type (str): "assignment", "release", or "set"
• level (optional): Target level for deployment
• deploy_implementation_time (optional): Scheduled time (ISO 8601)
• deploy_active (optional): Deploy to active libraries (boolean)
• response_format (optional): Output format

Examples:

Deploy assignment PLAY000001 to production
Deploy release REL001 to PRD level
Schedule deployment of assignment PLAY000001 for 2026-01-15T10:00:00Z

Set and Package Tools

ispw_list_sets

List all sets for a specific SRID.

Parameters:

• srid (str): System Resource Identifier
• set_id (optional): Filter by specific set ID
• response_format (optional): Output format

ispw_list_packages

List all packages for a specific SRID.

Parameters:

• srid (str): System Resource Identifier
• package_id (optional): Filter by specific package ID
• response_format (optional): Output format

ispw_get_package

Get detailed information about a specific package.

Parameters:

• srid (str): System Resource Identifier
• package_id (str): Package identifier
• response_format (optional): Output format

Architecture

Key Design Decisions

1. Comprehensive API Coverage: Implements all major ISPW REST API endpoints for complete workflow support
2. Dual Format Responses: Markdown for human readability, JSON for programmatic processing
3. Shared Utilities: DRY principle with reusable API client, error handling, and formatting functions
4. Strong Validation: Pydantic models ensure all inputs are validated before API calls
5. Async Design: All I/O operations use async/await for optimal performance
6. Flexible Configuration: Support for both production and custom CES servers

Project Structure

ispw-mcp-server/
├── ispw_mcp_server.py       # Main server implementation
├── ispw_openapi_spec.json   # OpenAPI specification (reference)
├── pyproject.toml           # Project configuration
├── .env.example             # Environment template
├── .env                     # Your configuration (not in git)
├── .gitignore              # Git ignore rules
└── README.md               # This file

Development

Running Tests

pytest

Code Quality

The project uses Ruff for linting:

ruff check .

Adding New Tools

When adding new ISPW API endpoints:

1. Define Pydantic input model with validation
2. Create tool function with @mcp.tool() decorator
3. Add proper annotations (readOnlyHint, destructiveHint, etc.)
4. Implement using shared _make_api_request() utility
5. Handle errors with _handle_api_error()
6. Support both markdown and JSON output formats
7. Update this README with tool documentation

Troubleshooting

Authentication Errors

Problem: "Error: Authentication failed. Check your ISPW_API_TOKEN is valid."

Solution:

• Verify your Personal Access Token is correct
• Ensure the token has appropriate permissions in CES
• Check token hasn't expired

Connection Errors

Problem: "Error: Request timed out. The ISPW server may be slow or unavailable."

Solution:

• Verify CES_HOST and CES_PORT are correct
• Check network connectivity to the CES server
• Increase ISPW_TIMEOUT if operations are legitimately slow

SSL Certificate Issues

Problem: SSL certificate verification fails for custom CES server

Solution: The server currently disables SSL verification for custom CES servers. For production use, configure proper SSL certificates.

Security Considerations

1. Token Management: Store ISPW_API_TOKEN securely, never commit to version control
2. SSL Verification: Consider enabling SSL verification for production deployments
3. Access Control: Tokens should have minimal required permissions
4. Audit Logging: ISPW maintains audit logs of all operations

Contributing

When contributing:

1. Follow Python best practices and PEP 8
2. Use type hints throughout
3. Add comprehensive docstrings
4. Include parameter validation
5. Test with both markdown and JSON formats
6. Update README documentation

License

[Specify your license here]

Support

For ISPW API issues, consult:

• BMC Compuware ISPW documentation
• BMC Compuware Support: https://www.bmc.com/support/

For MCP server issues:

• Check server logs
• Test with MCP Inspector
• Review environment configuration

Changelog

Version 1.0.0 (2026-01-08)

Initial release with:

• Complete assignment lifecycle management
• Task viewing capabilities
• Release creation and management
• Generate, promote, and deploy operations
• Set and package listing
• Dual output formats (Markdown/JSON)
• Comprehensive error handling
• Full Pydantic validation