Content
# BAW Admin MCP Server
An MCP (Model Context Protocol) server for managing IBM Business Automation Workflow (BAW) artifacts. This server provides tools for System, Container, Health Management, Version, and Task Instances operations through the BAW Operations REST API.
## Features
### System Operations
- **login**: Obtain CSRF prevention token
- **get_queue_status**: Check status of asynchronous operations
- **validate_database**: Validate the BAW database
### Container Operations
- **list_containers**: List all process applications and toolkits
- **get_container**: Get details of a specific container
- **create_container**: Create new process application or toolkit
- **count_containers**: Get count of containers
- **archive_container**: Archive a container
- **restore_container**: Restore an archived container
- **delete_container**: Delete a container
- **check_orphaned_containers**: Find orphaned toolkits
- **migrate_container_instances**: Migrate process instances between snapshots
- **install_container**: Install application from file
### Health Management Operations
- **delete_durable_messages**: Delete old durable subscription messages to reduce database storage
### Version Operations
- **list_versions**: List all snapshots or a subset of snapshots
- **get_version**: Get details of a specific snapshot
- **create_version**: Create new snapshots of process applications or toolkits
- **count_versions**: Get count of versions/snapshots
- **delete_versions**: Delete snapshots of process applications or toolkits
- **activate_version**: Activate a specified snapshot
- **deactivate_version**: Deactivate a snapshot
- **archive_version**: Archive a specified snapshot
- **restore_version**: Restore an archived snapshot
- **export_version**: Export a snapshot
- **install_version**: Install a process application on a connected workflow server
- **make_default_version**: Designate a default snapshot on a workflow server
- **stop_version**: Stop the BLA associated with a deactivated snapshot
- **create_offline_package**: Create an installation package for a snapshot
### Task Instances Operations
- **delete_completed_tasks**: Delete completed tasks to improve performance
## Prerequisites
- Python 3.8 or higher
- Git
- Access to IBM Business Automation Workflow server
- Valid BAW credentials
## Installation
### 1. Clone and Setup Repository
```bash
# The repository should already be initialized with git
# If not, run: git init
# Add aicoe-agent-utils submodule (if not already added)
git submodule add https://github.ibm.com/AI-CoE/aicoe-agent-utils.git
# Initialize submodules
git submodule update --init --recursive
```
**Note:** If you encounter SSH authentication issues, use HTTPS with credentials:
```bash
git submodule add https://github.ibm.com/AI-CoE/aicoe-agent-utils.git
# When prompted, enter your GitHub username and personal access token
```
### 2. Create Virtual Environment
```bash
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
### 3. Install Dependencies
```bash
pip install -r requirements.txt
```
### 4. Configure Environment
```bash
# Copy the example environment file
cp .env.example .env
# Edit .env with your BAW server details
# Required settings:
# - BAW_MCP_PORT: Port for the MCP server (default: 8000)
# - BAW_BASE_URL: Your BAW server URL (e.g., https://baw-server.com/bas/ops)
# - BAW_USERNAME: Your BAW username
# - BAW_PASSWORD: Your BAW password
```
Example `.env` file:
```env
BAW_MCP_PORT=8000
BAW_BASE_URL=https://your-baw-server.com/bas/ops
BAW_USERNAME=admin
BAW_PASSWORD=your_password
LOG_LEVEL=INFO
```
## Usage
### Running the MCP Server
```bash
# Start the MCP server
python3 baw_mcp_server.py
```
The server will be available at: `http://localhost:8000/mcp` (or your configured port)
### Testing the Server
```bash
# Run built-in tests
python3 baw_mcp_server.py test
```
This will test:
1. Login and CSRF token retrieval
2. Listing containers
3. Counting containers
### Using with AI Agents
Once the server is running, AI agents can connect to it and use the available tools. The server exposes all operations as MCP tools that can be called by compatible AI systems.
Example tool calls:
- `login(refresh_groups=False)` - Get CSRF token
- `list_containers(container_type="PA", size=10)` - List process applications
- `get_container(container_acronym="MYAPP")` - Get container details
- `create_container(name="My App", acronym="MYAPP", container_type="PA")` - Create new container
## Available Tools
### System Tools
#### login
Obtain IBM Business Automation Workflow CSRF prevention token.
**Parameters:**
- `refresh_groups` (bool, optional): Whether to refresh user's group membership
**Returns:** Dict with CSRF token and status
#### get_queue_status
Get status of an asynchronous operation.
**Parameters:**
- `operation_id` (str, required): Operation identifier
- `authorization_key` (str, optional): Authorization key from async operation
**Returns:** Dict with operation status
#### validate_database
Validate the BAW database.
**Returns:** Dict with validation results
### Container Tools
#### list_containers
Retrieve list of process applications and toolkits.
**Parameters:**
- `container_type` (str, optional): 'PA' or 'TK'
- `ids` (list, optional): Filter by container IDs
- `offset` (int, optional): Pagination offset
- `size` (int, optional): Max results
- `include_branches` (bool, optional): Include branches
- `include_versions` (bool, optional): Include versions
**Returns:** Dict with container list
#### get_container
Get details of a specific container.
**Parameters:**
- `container_acronym` (str, required): Container acronym
- `include_branches` (bool, optional): Include branches
- `include_versions` (bool, optional): Include versions
**Returns:** Dict with container details
#### create_container
Create a new process application or toolkit.
**Parameters:**
- `name` (str, required): Full name
- `acronym` (str, required): Short acronym
- `container_type` (str, required): 'PA' or 'TK'
- `description` (str, optional): Description
- `short_name` (str, optional): Short name
**Returns:** Dict with created container
#### count_containers
Get count of containers.
**Parameters:**
- `container_type` (str, optional): 'PA' or 'TK'
**Returns:** Dict with count
#### archive_container
Archive a container.
**Parameters:**
- `container_acronym` (str, required): Container to archive
**Returns:** Dict with operation result
#### restore_container
Restore an archived container.
**Parameters:**
- `container_acronym` (str, required): Container to restore
**Returns:** Dict with operation result
#### delete_container
Delete a container.
**Parameters:**
- `container_acronym` (str, required): Container to delete
**Returns:** Dict with operation result
#### check_orphaned_containers
Find orphaned toolkits.
**Returns:** Dict with list of orphaned toolkits
#### migrate_container_instances
Migrate process instances between snapshots.
**Parameters:**
- `container_acronym` (str, required): Process application acronym
- `source_snapshot` (str, required): Source snapshot acronym
- `target_snapshot` (str, required): Target snapshot acronym
**Returns:** Dict with async operation details
#### install_container
Install an application on Workflow Server or Workflow Center from a file.
**Parameters:**
- `file_path` (str, required): Path to installation package (.zip or .twx)
- `inactive` (bool, optional): Deactivate snapshot after installation
- `case_dos_name` (str, optional): Case design object store name
- `case_project_area` (str, optional): Target environment for case artifacts
- `case_overwrite` (bool, optional): Overwrite existing case artifacts
**Returns:** Dict with async operation details
### Health Management Tools
#### delete_durable_messages
Delete old durable subscription messages to reduce database storage.
**Parameters:**
- `older_than` (int, required): Age in days (must be > 0). Messages older than this are deleted. Interpreted as 24-hour periods, not calendar days.
- `maximum_duration` (int, optional): Maximum duration of deletion operation in minutes (default: 0 = unlimited)
- `transaction_slice` (int, optional): Number of messages to delete per transaction (default: 1000)
**Returns:** Dict with async operation details
### Version Tools
#### list_versions
Retrieve information about all snapshots or a subset of snapshots.
**Parameters:**
- `container_acronym` (str, required): Process application or toolkit acronym
- `version_ids` (list, optional): Filter by specific snapshot IDs
- `branch` (str, optional): Track acronym to filter snapshots
- `offset` (int, optional): Pagination offset
- `size` (int, optional): Maximum number of snapshots to return
**Returns:** Dict with list of versions/snapshots
#### get_version
Get details of a specific snapshot.
**Parameters:**
- `container_acronym` (str, required): Process application or toolkit acronym
- `version_acronym` (str, required): Snapshot acronym
**Returns:** Dict with version details
#### create_version
Create new snapshots of process applications or toolkits.
**Parameters:**
- `container_acronym` (str, required): Process application or toolkit acronym
- `name` (str, required): Snapshot name
- `description` (str, optional): Snapshot description
- `branch_name` (str, optional): Track name
**Returns:** Dict with created version details
#### count_versions
Get count of versions/snapshots for a container.
**Parameters:**
- `container_acronym` (str, required): Process application or toolkit acronym
- `branch` (str, optional): Track acronym to filter count
**Returns:** Dict with version count
#### delete_versions
Delete snapshots of process applications or toolkits.
**Parameters:**
- `container_acronym` (str, required): Process application or toolkit acronym
- `branch_name` (str, optional): Workflow Center only - Track name
- `versions` (list, optional): List of snapshot acronyms to delete
- `force` (bool, optional): Workflow Server only - Delete last/default snapshot
- `kept_number` (int, optional): Workflow Center only - Number of unnamed snapshots to keep
- `created_before` (str, optional): Workflow Center only - Delete snapshots created before this time (ISO 8601)
- `created_after` (str, optional): Workflow Center only - Delete snapshots created after this time (ISO 8601)
- `created_before_version` (str, optional): Workflow Center only - Named snapshot acronym reference
- `delete_archived` (bool, optional): Workflow Center only - Delete archived snapshots
- `continue_on_error` (bool, optional): Workflow Server only - Continue if error occurs
**Returns:** Dict with async operation details
#### activate_version
Activate a specified process application snapshot or toolkit snapshot.
**Parameters:**
- `container_acronym` (str, required): Process application or toolkit acronym
- `version_acronym` (str, required): Snapshot acronym to activate
**Returns:** Dict with activation result
#### deactivate_version
Deactivate a process application snapshot or toolkit snapshot.
**Parameters:**
- `container_acronym` (str, required): Process application or toolkit acronym
- `version_acronym` (str, required): Snapshot acronym to deactivate
**Returns:** Dict with deactivation result
#### archive_version
Archive a specified process application snapshot or toolkit snapshot.
**Parameters:**
- `container_acronym` (str, required): Process application or toolkit acronym
- `version_acronym` (str, required): Snapshot acronym to archive
**Returns:** Dict with archive result
#### restore_version
Restore a specified process application snapshot or toolkit snapshot that is archived.
**Parameters:**
- `container_acronym` (str, required): Process application or toolkit acronym
- `version_acronym` (str, required): Snapshot acronym to restore
**Returns:** Dict with restore result
#### export_version
Export a snapshot to a file.
**Parameters:**
- `container_acronym` (str, required): Process application or toolkit acronym
- `version_acronym` (str, required): Snapshot acronym to export
- `export_path` (str, optional): Path where to save the exported file
**Returns:** Dict with export result and file location
#### install_version
Install a process application snapshot on a connected workflow server.
**Parameters:**
- `container_acronym` (str, required): Process application acronym
- `version_acronym` (str, required): Snapshot acronym to install
- `server_name` (str, required): Target workflow server name
- `inactive` (bool, optional): Deactivate snapshot after installation
**Returns:** Dict with async operation details
#### make_default_version
Designate a default snapshot on a workflow server.
**Parameters:**
- `container_acronym` (str, required): Process application acronym
- `version_acronym` (str, required): Snapshot acronym to make default
**Returns:** Dict with operation result
#### stop_version
Stop the BLA (Business Level Application) associated with a deactivated snapshot on a workflow server.
**Parameters:**
- `container_acronym` (str, required): Process application acronym
- `version_acronym` (str, required): Snapshot acronym
**Returns:** Dict with operation result
#### create_offline_package
Create an installation package for a process application snapshot.
**Parameters:**
- `container_acronym` (str, required): Process application acronym
- `version_acronym` (str, required): Snapshot acronym
- `server_name` (str, optional): Target server name for package
**Returns:** Dict with async operation details
### Task Instances Tools
#### delete_completed_tasks
Delete completed tasks associated with running process instances.
**Parameters:**
- `task_status` (str, required): Status of tasks to delete: 'CLOSED', 'SENT', 'ACTIONED', 'ALERT', or 'ALL_COMPLETED'
- `container` (str, optional): Process application acronym (required if task_ids not specified)
- `version` (str, optional): Snapshot acronym (defaults to Tip/default)
- `task_type` (str, optional): Type: 'SYSTEM_TASK', 'USER_TASK', 'DECISION_TASK', or 'ALL' (default: 'ALL')
- `task_ids` (list, optional): Specific task IDs to delete (required if container not specified)
- `process_name` (str, optional): Specific process to clean up
- `ended_after` (str, optional): Delete tasks ended on or after this time
- `ended_before` (str, optional): Delete tasks ended on or before this time
- `maximum_duration` (int, optional): Maximum time in minutes (default: 0 = no limit)
- `transaction_slice` (int, optional): Tasks to delete per transaction (default: 100)
**Returns:** Dict with async operation details
## Project Structure
```
BAW-Admin/
├── aicoe-agent-utils/ # Git submodule
├── baw_mcp_server.py # Main MCP server implementation
├── __init__.py # Package initialization
├── requirements.txt # Python dependencies
├── .env.example # Environment template
├── .env # Your configuration (not in git)
├── .gitignore # Git ignore rules
├── .gitmodules # Git submodule config
├── baw-ops.json # BAW API specification
└── README.md # This file
```
## Development
### Adding New Operations
To add new BAW operations:
1. Review the `baw-ops.json` file for available API endpoints
2. Add a new `@tool` decorated async method to the `BAWAdminMCP` class
3. Follow the existing pattern:
- Include `ctx: Context` as first parameter
- Add comprehensive docstring with Args and Returns
- Use `_make_request()` helper for API calls
- Handle errors appropriately
Example:
```python
@tool
async def my_new_operation(
self,
ctx: Context,
param1: str,
param2: Optional[int] = None
) -> Dict[str, Any]:
"""
Description of the operation.
Args:
ctx: MCP context
param1: Description of param1
param2: Description of param2
Returns:
Dict containing the operation result
"""
params = {"param1": param1}
if param2:
params["param2"] = param2
return await self._make_request(
"GET",
"/std/bpm/your/endpoint",
params=params
)
```
### Testing
Always test new operations:
```bash
# Add test cases to the test() method
python3 baw_mcp_server.py test
```
## Troubleshooting
### Submodule Issues
If you have trouble with the submodule:
```bash
# Remove and re-add submodule
git submodule deinit -f aicoe-agent-utils
rm -rf .git/modules/aicoe-agent-utils
git rm -f aicoe-agent-utils
git submodule add https://github.ibm.com/AI-CoE/aicoe-agent-utils.git
git submodule update --init --recursive
```
### Import Errors
If you see import errors:
```bash
# Ensure virtual environment is activated
source venv/bin/activate
# Reinstall dependencies
pip install -r requirements.txt
```
### Connection Issues
If you can't connect to BAW server:
1. Verify `BAW_BASE_URL` in `.env` is correct
2. Check network connectivity to BAW server
3. Verify credentials are correct
4. Check if SSL certificate verification is needed (set `verify=True` in `httpx.AsyncClient`)
### CSRF Token Issues
If CSRF token fails:
1. Ensure credentials are correct
2. Check if user has proper permissions
3. Try calling `login()` tool explicitly first
## Security Notes
- Never commit `.env` file with credentials
- Use environment variables for sensitive data
- In production, enable SSL certificate verification
- Restrict access to the MCP server port
- Use strong passwords for BAW accounts
- Regularly rotate credentials
## License
This project is licensed under the Apache License 2.0.
## Support
For issues and questions:
- Check the BAW Operations API documentation
- Review the aicoe-agent-utils documentation
- Contact your BAW administrator for server-specific issues
## Future Enhancements
Planned additions:
- Branch operations (tracks) - partially implemented
- Environment variable management
- Team binding operations
- Exposed Process Values (EPV) management
- Event Manager operations
- Process operations - partially implemented
- User management operations
- REST Server operations
- Web Service operations
- Migration policy operations
- Workflow server management
