Skip to content

Commit c15ff3b

Browse files
tiwilliatiwillia
committed
Add generated requirements spec files
1 parent 63d2c81 commit c15ff3b

File tree

9 files changed

+301
-0
lines changed

9 files changed

+301
-0
lines changed

‎spec/requirements/.current-requirement

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
2025-08-06-1135-rosa-hcp-mcp-server

‎spec/requirements/2025-08-06-1135-rosa-hcp-mcp-server/00-initial-request.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Initial Request
2+
3+
**Timestamp:** 2025-08-06 11:35
4+
5+
**Request:** Build an MCP server for ROSA HCP (Red Hat OpenShift on AWS using Hosted Control Planes) to enable AI assistants to integrate with Red Hat Managed OpenShift services.
6+
7+
## Full Requirements from initial_requirements.md
8+
9+
Build an MCP server for ROSA HCP (Red Hat OpenShift on AWS using Hosted Control Planes) to enable AI assistants to integrate with Red Hat Managed OpenShift services. The server should provide a minimal MVP implementation focusing on essential cluster operations and documentation.
10+
11+
### Solution Overview
12+
A golang-based MCP server following the business logic established in the python-based OCM MCP server https://github.com/redhat-ai-tools/ocm-mcp/ . The structure and best practices of the solution should follow the excellent examples set by the golang-based OpenShift MCP server https://github.com/openshift/openshift-mcp-server, using the same https://github.com/mark3labs/mcp-go framework.
13+
14+
### Core Requirements
15+
- 4 core tools: List Clusters, Get Cluster Details, Create ROSA HCP Cluster, Get Authenticated Account
16+
- 1 resource: ROSA HCP Prerequisites Documentation
17+
- OAuth token-based authentication using OCM offline tokens
18+
- Support both stdio and SSE transport modes
19+
- Integration with OCM API endpoints at https://api.openshift.com

‎spec/requirements/2025-08-06-1135-rosa-hcp-mcp-server/01-discovery-questions.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Discovery Questions
2+
3+
## Q1: Will this MCP server be deployed as a standalone service that AI assistants connect to remotely?
4+
**Default if unknown:** Yes (most MCP servers run as independent services for multiple AI assistant connections)
5+
6+
## Q2: Should the server support multiple concurrent OCM authentication tokens from different users?
7+
**Default if unknown:** No (MVP should focus on single-user authentication for simplicity)
8+
9+
## Q3: Will users need to create ROSA HCP clusters in different AWS regions beyond us-east-1?
10+
**Default if unknown:** Yes (multi-region support is standard for production ROSA deployments)
11+
12+
## Q4: Should the server cache cluster information to reduce OCM API calls?
13+
**Default if unknown:** No (real-time data accuracy is more important than performance for an MVP)
14+
15+
## Q5: Will this server need to handle ROSA HCP cluster lifecycle beyond creation (scaling, upgrading, deletion)?
16+
**Default if unknown:** No (MVP focuses on essential operations - creation and monitoring)

‎spec/requirements/2025-08-06-1135-rosa-hcp-mcp-server/02-discovery-answers.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Discovery Answers
2+
3+
## Q1: Will this MCP server be deployed as a standalone service that AI assistants connect to remotely?
4+
**Answer:** Yes - SSE transport with X-OCM-OFFLINE-TOKEN header support
5+
6+
## Q2: Should the server support multiple concurrent OCM authentication tokens from different users?
7+
**Answer:** Yes
8+
9+
## Q3: Will users need to create ROSA HCP clusters in different AWS regions beyond us-east-1?
10+
**Answer:** Yes, but us-east-1 should be the default if no region is specified
11+
12+
## Q4: Should the server cache cluster information to reduce OCM API calls?
13+
**Answer:** No
14+
15+
## Q5: Will this server need to handle ROSA HCP cluster lifecycle beyond creation (scaling, upgrading, deletion)?
16+
**Answer:** Not for the MVP

‎spec/requirements/2025-08-06-1135-rosa-hcp-mcp-server/03-context-findings.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Context Findings
2+
3+
## Current Codebase State
4+
- **Status:** Fresh project - no existing Go code
5+
- **Available files:**
6+
- `initial_requirements.md` - Comprehensive requirements document
7+
- `example_cluster_create_request.json` - Example OCM API request for ROSA HCP cluster creation
8+
9+
## Reference Implementation Analysis
10+
11+
### Python OCM MCP Server (ocm_mcp_server.py)
12+
**Key Patterns:**
13+
- Uses FastMCP framework with `@mcp.tool()` decorators
14+
- Token handling: Environment variable for stdio, HTTP header `X-OCM-Offline-Token` for SSE
15+
- OAuth refresh flow: POST to SSO with `refresh_token` grant type
16+
- Response formatting: Dedicated `format_clusters_response()` functions
17+
- Error handling: Direct `response.raise_for_status()` without retry logic
18+
- Transport detection: `MCP_TRANSPORT` environment variable
19+
20+
### Go OpenShift MCP Server Patterns
21+
**Architecture:**
22+
- Uses `github.com/mark3labs/mcp-go` framework version 0.37.0
23+
- Server struct with configuration and kubernetes manager
24+
- Profile-based tool registration system
25+
- Middleware support for authentication and logging
26+
- Both stdio and SSE transport support with context functions
27+
28+
**Authentication:**
29+
- OAuth header support: `Authorization` and custom fallback headers
30+
- Context-based token passing
31+
- Middleware for scoped authorization
32+
33+
**Transport Support:**
34+
- `ServeStdio()` for stdio transport
35+
- `ServeSse()` for SSE with base URL and HTTP server options
36+
- Context functions for header extraction
37+
38+
## Technical Architecture Plan
39+
- **Framework:** `github.com/mark3labs/mcp-go`
40+
- **Structure:** Follow OpenShift MCP server patterns (Server struct, Configuration, Profile)
41+
- **Authentication:** OCM offline token → OAuth access token flow (like Python reference)
42+
- **Transport:** Both stdio and SSE with `X-OCM-OFFLINE-TOKEN` header support
43+
- **API Client:** HTTP client for OCM API calls
44+
- **Formatting:** Dedicated formatter functions for human-readable output
45+
46+
## Implementation Patterns Required
47+
- Server struct with OCM client manager
48+
- Configuration struct for settings
49+
- Profile system for tool registration
50+
- Context-based token handling for SSE transport
51+
- Direct API error propagation without retry logic
52+
- Formatter functions returning strings (not JSON)

‎spec/requirements/2025-08-06-1135-rosa-hcp-mcp-server/04-detail-questions.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Expert Detail Questions
2+
3+
## Q6: Should the create_rosa_hcp_cluster tool require ALL ROSA HCP parameters (AWS account, role ARNs, OIDC config, subnet IDs) to be provided by the user?
4+
**Default if unknown:** No (provide sensible defaults for MVP, require only cluster name and optionally region)
5+
6+
## Q7: Should we implement the same profile system as the OpenShift MCP server (e.g., "rosa-basic", "rosa-full") to control which tools are available?
7+
**Default if unknown:** No (expose all 4 tools by default for MVP simplicity)
8+
9+
## Q8: Should the X-OCM-OFFLINE-TOKEN header support follow the exact pattern from ocm_mcp_server.py with fallback to environment variable for stdio transport?
10+
**Default if unknown:** Yes (maintains compatibility with existing AI assistant integrations)
11+
12+
## Q9: Should cluster creation return the raw OCM API response JSON or a formatted human-readable string like the other tools?
13+
**Default if unknown:** Formatted string (consistent with other tool responses and human readability requirements)
14+
15+
## Q10: Should the server validate that provided AWS IAM role ARNs exist before making the cluster creation API call?
16+
**Default if unknown:** No (let OCM API handle validation and return meaningful errors directly to the user)

‎spec/requirements/2025-08-06-1135-rosa-hcp-mcp-server/05-detail-answers.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Expert Detail Answers
2+
3+
## Q6: Should the create_rosa_hcp_cluster tool require ALL ROSA HCP parameters (AWS account, role ARNs, OIDC config, subnet IDs) to be provided by the user?
4+
**Answer:** Yes - require everything listed (AWS account, role ARNs, OIDC config, subnet IDs). These are user-specific and must be set up beforehand. Region can have a sensible default.
5+
6+
## Q7: Should we implement the same profile system as the OpenShift MCP server (e.g., "rosa-basic", "rosa-full") to control which tools are available?
7+
**Answer:** No - expose all 4 tools by default for MVP simplicity. Consider as future option.
8+
9+
## Q8: Should the X-OCM-OFFLINE-TOKEN header support follow the exact pattern from ocm_mcp_server.py with fallback to environment variable for stdio transport?
10+
**Answer:** Yes - X-OCM-OFFLINE-TOKEN header for SSE transport, with fallback to OCM_OFFLINE_TOKEN environment variable for stdio transport.
11+
12+
## Q9: Should cluster creation return the raw OCM API response JSON or a formatted human-readable string like the other tools?
13+
**Answer:** Formatted string
14+
15+
## Q10: Should the server validate that provided AWS IAM role ARNs exist before making the cluster creation API call?
16+
**Answer:** No - let OCM API handle validation. Note: this may change after the MVP.

‎spec/requirements/2025-08-06-1135-rosa-hcp-mcp-server/06-requirements-spec.md

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# ROSA HCP MCP Server - Comprehensive Requirements Specification
2+
3+
## Problem Statement
4+
Build a golang-based MCP server for ROSA HCP (Red Hat OpenShift on AWS using Hosted Control Planes) that enables AI assistants to integrate with Red Hat Managed OpenShift services. The server provides essential cluster operations through the Model Context Protocol.
5+
6+
## Solution Overview
7+
A minimal MVP implementation following the architectural patterns of the OpenShift MCP server (github.com/openshift/openshift-mcp-server) and business logic of the OCM MCP server (github.com/redhat-ai-tools/ocm-mcp), using the mcp-go framework (github.com/mark3labs/mcp-go).
8+
9+
## Functional Requirements
10+
11+
### Core Tools (4 Required)
12+
13+
#### 1. `whoami()`
14+
- **Description:** "Get the authenticated account"
15+
- **Parameters:** None
16+
- **Returns:** Formatted account information (username, organization, etc.)
17+
- **Implementation:** GET `/api/accounts_mgmt/v1/current_account`
18+
19+
#### 2. `get_clusters(state: string)`
20+
- **Description:** "Retrieves the list of clusters"
21+
- **Parameters:**
22+
- `state` (required): Filter clusters by state (e.g., "ready", "installing", "error")
23+
- **Returns:** Formatted cluster list with name, ID, API URL, console URL, state, version
24+
- **Implementation:** GET `/api/clusters_mgmt/v1/clusters` with state filtering
25+
26+
#### 3. `get_cluster(cluster_id: string)`
27+
- **Description:** "Retrieves the details of the cluster"
28+
- **Parameters:**
29+
- `cluster_id` (required): Unique cluster identifier
30+
- **Returns:** Formatted detailed cluster information
31+
- **Implementation:** GET `/api/clusters_mgmt/v1/clusters/{cluster_id}`
32+
33+
#### 4. `create_rosa_hcp_cluster(...)`
34+
- **Description:** "Provision a new ROSA HCP cluster with required configuration"
35+
- **Parameters (all required except region):**
36+
- `cluster_name` (required): Name for the cluster
37+
- `aws_account_id` (required): AWS account ID
38+
- `billing_account_id` (required): AWS billing account ID
39+
- `role_arn` (required): IAM installer role ARN
40+
- `operator_role_prefix` (required): Operator role prefix
41+
- `oidc_config_id` (required): OIDC configuration ID
42+
- `subnet_ids` (required): Array of subnet IDs
43+
- `region` (optional): AWS region (default: "us-east-1")
44+
- **Returns:** Formatted cluster creation response
45+
- **Implementation:** POST `/api/clusters_mgmt/v1/clusters` with ROSA HCP payload
46+
47+
### Resources (1 Required)
48+
49+
#### 1. ROSA HCP Prerequisites Documentation
50+
- **Type:** Static resource
51+
- **Content:** Documentation of cluster creation requirements
52+
- **Includes:** IAM role setup, OIDC configuration, networking prerequisites
53+
54+
## Technical Requirements
55+
56+
### Architecture
57+
- **Framework:** `github.com/mark3labs/mcp-go` v0.37.0+
58+
- **Structure:** Follow OpenShift MCP server patterns
59+
- `Server` struct with OCM client manager
60+
- `Configuration` struct for settings
61+
- Profile system (expose all tools for MVP)
62+
- Context-based authentication handling
63+
64+
### Authentication
65+
- **Token Source:** OCM offline tokens from https://console.redhat.com/openshift/token
66+
- **Flow:** OAuth refresh token → access token
67+
- **Transport Handling:**
68+
- **SSE Transport:** `X-OCM-OFFLINE-TOKEN` header
69+
- **Stdio Transport:** `OCM_OFFLINE_TOKEN` environment variable
70+
- **Multiple Users:** Support concurrent tokens via header-based authentication
71+
72+
### Transport Support
73+
- **Stdio:** Standard input/output for local integrations
74+
- **SSE:** Server-Sent Events with HTTP headers for remote access
75+
- **Configuration:** Command-line flags and TOML config files
76+
77+
### API Integration
78+
- **SDK:** Use `github.com/openshift-online/ocm-sdk-go` for OCM API client
79+
- **Base URL:** https://api.openshift.com (configurable)
80+
- **Authentication:** Bearer token via OAuth refresh flow (handled by OCM SDK)
81+
- **Endpoints:**
82+
- OCM Clusters_mgmt API: `/api/clusters_mgmt/v1/`
83+
- OCM Accounts_mgmt API: `/api/accounts_mgmt/v1/`
84+
- **Error Handling:** Direct API error propagation without retry logic
85+
86+
### Response Formatting
87+
- **Output:** Human-readable formatted strings (not JSON)
88+
- **Patterns:** Dedicated formatter functions like `formatClustersResponse()`
89+
- **Consistency:** All tools return formatted text for AI assistant consumption
90+
91+
### Configuration
92+
- **Methods:** Command-line flags, environment variables, TOML config files
93+
- **Required Settings:**
94+
- OCM API base URL (default: https://api.openshift.com)
95+
- Transport mode selection
96+
- Optional: Port for SSE/HTTP transport
97+
- Optional: SSE base URL for public endpoints
98+
99+
## Implementation Hints
100+
101+
### File Structure (following OpenShift MCP patterns)
102+
```
103+
cmd/rosa-mcp-server/main.go # Entry point
104+
pkg/
105+
config/config.go # Configuration management
106+
ocm/
107+
client.go # OCM SDK client wrapper
108+
auth.go # OAuth token handling (via OCM SDK)
109+
formatter.go # Response formatting
110+
mcp/
111+
server.go # MCP server implementation
112+
tools.go # Tool implementations
113+
profiles.go # Profile definitions
114+
version/version.go # Version information
115+
```
116+
117+
### Key Patterns to Follow
118+
1. **Server Initialization:** Similar to `mcp.NewServer()` in OpenShift MCP
119+
2. **Context Handling:** Extract tokens from headers/environment in context functions
120+
3. **Tool Registration:** Register all 4 tools with the mcp-go framework
121+
4. **Error Wrapping:** Use `NewTextResult()` pattern for consistent error responses
122+
5. **Middleware:** Logging middleware for tool calls
123+
124+
### Critical Dependencies
125+
- `github.com/mark3labs/mcp-go` - MCP framework
126+
- `github.com/openshift-online/ocm-sdk-go` - OCM API client SDK
127+
- `github.com/BurntSushi/toml` - Configuration files
128+
- `github.com/spf13/cobra` - CLI interface
129+
130+
## Acceptance Criteria
131+
1. **Transport Support:** Both stdio and SSE work with token authentication
132+
2. **Tool Functionality:** All 4 tools return properly formatted responses
133+
3. **Error Handling:** OCM API errors are exposed to users without modification
134+
4. **Multi-Region:** Cluster creation supports configurable AWS regions
135+
5. **Authentication:** Multiple concurrent users supported via header tokens
136+
6. **Documentation:** Prerequisites resource available to clients
137+
7. **Configuration:** Configurable via CLI, environment, and config files
138+
139+
## Assumptions
140+
- Users have pre-configured AWS IAM roles and OIDC configurations
141+
- OCM API handles all parameter validation for cluster creation
142+
- No caching required - real-time API data preferred
143+
- MVP scope excludes cluster lifecycle management beyond creation
144+
- Unit testing sufficient for MVP (integration tests future enhancement)
145+
- Profile system will be simple (all tools enabled) with future configurability
146+
147+
## Future Considerations (Do not implement in MVP)
148+
- Tool selection profiles (rosa-basic, rosa-full)
149+
- Pre-validation of AWS resources before API calls
150+
- Cluster lifecycle operations (scaling, upgrading, deletion)
151+
- Caching for performance optimization
152+
- Enhanced error recovery and retry logic

‎spec/requirements/2025-08-06-1135-rosa-hcp-mcp-server/metadata.json

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"id": "rosa-hcp-mcp-server",
3+
"started": "2025-08-06T11:35:00Z",
4+
"lastUpdated": "2025-08-06T11:35:00Z",
5+
"status": "active",
6+
"phase": "complete",
7+
"progress": {
8+
"discovery": { "answered": 5, "total": 5 },
9+
"detail": { "answered": 5, "total": 5 }
10+
},
11+
"contextFiles": [],
12+
"relatedFeatures": []
13+
}

0 commit comments

Comments
 (0)