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

Related MCP server: Lazy LLMs Project Management MCP Server

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