feat: add polkadot upgrade workflow tools and prompts (#33)

* feat: add polkadot upgrade workflow tools and prompts

- Add list_polkadot_releases tool to discover available SDK releases
- Add find_runtime_pallets tool to analyze project runtime configurations
- Add polkadot_upgrade prompt for systematic release impact analysis
- Enhance fetch_and_analyze_release with PR labels and structured output
- Add GitHub API authentication support via GITHUB_TOKEN env var
- Use zeroize crate for secure token handling
- Add comprehensive test coverage for runtime discovery

* fix: make substrate node integration test skip when binary unavailable

- Add is_available() method to check for substrate-node binary
- Skip test gracefully with informative message when binary not found
- Prevents test failure in CI/environments without substrate-node installed

* fix: make substrate node test fail with clear error when binary missing

- Change from skipping to panicking when substrate-node not found
- Provide clear error message about requirement to install substrate-node
- Ensures CI/developers are aware of the dependency requirement

* refactor: simplify fetch_and_analyze_release naming

- Remove '_enhanced' suffix from fetch_and_analyze_release_enhanced
- Update all references to use simplified name
- No functional changes, just naming consistency

* fmt

Signed-off-by: Michael Assaf <[email protected]>

* feat: enhance polkadot upgrade prompt with parallel sub-agent architecture

- Add comprehensive workflow documentation with agent coordination
- Implement three-agent system: Main Orchestrator, Compilation, and Analysis agents
- Add evidence-based impact categorization (MUST/OPTIONAL/INHERITED/DON'T KNOW)
- Include detailed tracking tables and structured reporting
- Add mermaid diagrams for workflow visualization
- Enhance prompt template with specific sub-agent instructions
- Normalize release input to handle different git tag formats
- Add comprehensive README documenting the upgrade analysis process

* feat: enhance polkadot upgrade prompt with parallel sub-agent architecture

- Add ULTRATHINK directive for improved analysis
- Implement batch processing for PR analysis (10 parallel agents per batch)
- Create dedicated analysis directory structure for individual PR reports
- Update tracking table to include total PR count and link to analysis files
- Add force parameter to fetch_and_analyze_release for cache control
- Implement cache loading functionality to avoid redundant downloads
- Improve compilation sub-agent requirements and constraints
- Clarify single PR analysis requirement for each sub-agent
- Add structured report writing to designated analysis files

* optimize prompt, use dyn for mock github api client, add caching for
fetch and analyze release

Signed-off-by: Michael Assaf <[email protected]>

* remove compilation sub agent from workflow

* pay close attention to template code in pr changes

* send logs to stderr

---------

Signed-off-by: Michael Assaf <[email protected]>

Author: snowmead

Cargo.lock

@@ -42,6 +42,10 @@ scale-value = { version = "0.16", features = ["from-string"] }
 scale-info = "2.11"
 sp-core = "33.0"
 tokio-util = "0.7.16"
+zeroize = "1.8"
+ignore = "0.4.23"
+async-trait = "0.1"
 
 [dev-dependencies]
 rmcp = { version = "0.6.3", features = ["transport-io", "client"] }
+tempfile = "3.22.0"

Cargo.toml

@@ -2,23 +2,26 @@
 
 An MCP (Model Context Protocol) server that provides tools for working with Substrate-based blockchains.
 
-
 ## Installation
 
 ### Option 1: Install from GitHub
+
 ```bash
 cargo install --locked --git https://github.com/Moonsong-Labs/substrate-mcp
 ```
 
 ### Option 2: Build locally (Requires cargo)
+
 ```bash
 cargo build --release
 ```
+
 The binary will be available at `./target/release/substrate-mcp`
 
 ## Prerequisites
 
 For the `subxt_execute` tool, install the subxt CLI:
+
 ```bash
 cargo install subxt-cli
 ```
@@ -51,14 +54,51 @@ If you built the server locally instead of installing it, use the full path:
 
 Alternatively, you can add using cli:
 
-```claude mcp add substrate /path/to/substrate-mcp/target/release/substrate-mcp```
+```
+claude mcp add substrate /path/to/substrate-mcp/target/release/substrate-mcp
+```
+
+## Configuration
+
+### GitHub API Rate Limits
+
+Some tools (like `fetch_and_analyze_release` and `list_polkadot_releases`) make requests to the GitHub API. Without authentication, you're limited to 60 requests per hour. For higher rate limits (5,000 requests/hour), set a GitHub token:
+
+```bash
+export GITHUB_TOKEN="your_github_personal_access_token"
+```
+
+To generate a token:
+
+1. Go to [GitHub Settings > Personal access tokens](https://github.com/settings/tokens)
+2. Click "Generate new token" > "Generate new token (classic)"
+3. No special permissions required - just create a basic token
+4. Copy the token and set it in your environment
+
+For Claude Code, you can set environment variables in your configuration:
+
+```json
+{
+  "mcpServers": {
+    "substrate-mcp": {
+      "command": "substrate-mcp",
+      "env": {
+        "GITHUB_TOKEN": "your_github_personal_access_token"
+      }
+    }
+  }
+}
+```
 
 ## Available Tools
 
 ### Release Analysis
+
 - **`fetch_and_analyze_release`** - Fetches and analyzes a Polkadot SDK release - downloads PRDocs and generates summaries (manifest, crate changes, audience breakdown)
+- **`list_polkadot_releases`** - List all available Polkadot SDK releases from the polkadot-sdk repository. Helps discover valid release identifiers before using other tools. Supports filtering by release type (stable, legacy, or all)
 
 ### Chain Exploration
+
 - **`subxt_execute`** - Use subxt to decode and explore Substrate blockchain data. Useful for: analyzing chain metadata structure, generating type-safe Rust code for chain interactions, exploring available pallets/calls/storage/events, decoding extrinsics and storage values, and understanding runtime APIs
 - **`filter_metadata`** - Filter and search chain metadata to discover available pallets, storage entries, calls, events, constants, and errors. Supports partial name matching for easy discovery
 - **`query_extrinsics`** - Query extrinsics from blocks. Supports filtering by pallet, call name, and signer address. Returns decoded transaction data including signer, call info, and arguments
@@ -67,8 +107,8 @@ Alternatively, you can add using cli:
 - **`list_pallet_storage`** - List all storage entries available in a specific pallet. Use this to discover what storage items are available before querying them
 
 ### Extrinsic Operations
-- **`submit_dev_extrinsic`** - Submit a generic extrinsic to a Substrate chain using dev accounts. Supports any pallet call with arbitrary arguments. Use dev account names like 'alice', 'bob', 'charlie', etc. for signing
 
+- **`submit_dev_extrinsic`** - Submit a generic extrinsic to a Substrate chain using dev accounts. Supports any pallet call with arbitrary arguments. Use dev account names like 'alice', 'bob', 'charlie', etc. for signing
 
 ## Available Prompts
 
@@ -77,30 +117,46 @@ The Substrate MCP server provides several specialized prompts for Substrate deve
 ### Polkadot SDK Release Analysis
 
 #### release_comparison
-**Description**: List changes between two polkadot-sdk release versions  
+
+**Description**: List changes between two polkadot-sdk release versions
 **Arguments**:
+
 - `current_version` (required): Version currently being used
 - `target_version` (required): Version dev wants to compare with (must be greater than current)
 - `specific_changes` (optional): What specific changes to look for (e.g: was there any change in `pallet_treasury` ?)
 
 #### analyze_release
-**Description**: Analyze how specific release(s) impact your current project  
+
+**Description**: Analyze how specific release(s) impact your current project
 **Arguments**:
+
 - `release` (required): The release version(s) to analyze. Examples: 'stable2503-7' for single release, 'stable2502,stable2503' for comparison
 - `focus` (optional): Specific aspect to focus on (e.g., 'breaking changes', 'migrations', 'security'). Leave empty for comprehensive analysis
 
+#### polkadot_upgrade
+
+**Description**: User and agent discovery and discussion on what is needed to upgrade polkadot version in your substrate client and runtime
+**Arguments**:
+
+- `release` (required): Release name/version to analyze
+- `focus` (optional): Specific area to focus analysis on
+
 ### Development & Scaffolding
 
 #### scaffold_pallet
-**Description**: Generate pallet structure and implementation templates  
+
+**Description**: Generate pallet structure and implementation templates
 **Arguments**:
+
 - `pallet_description` (required): Description for the pallet
 
 ### Security Analysis
 
 #### security_review
-**Description**: Security review covering code security, economic threats, and performance analysis  
+
+**Description**: Security review covering code security, economic threats, and performance analysis
 **Arguments**:
+
 - `target` (required): Target component/pallet/system to review
 
 This prompt combines code security audit, economic security assessment, threat modeling, and weight analysis into a comprehensive security review. NOTE: This prompt is designed to be used during development as a tool to provide an extra layer of analysis. It is not meant to replace professional security audits.

README.md

@@ -20,7 +20,8 @@ mod utils;
 use utils::catch_panic_as_mcp_error;
 
 use crate::service::prompts::{
-    analyze_release, get_started, release_comparison, scaffold_pallet, security_review,
+    analyze_release, get_started, polkadot_upgrade, release_comparison, scaffold_pallet,
+    security_review,
 };
 
 #[cfg(test)]
@@ -58,6 +59,24 @@ impl SubstrateService {
         catch_panic_as_mcp_error(tools::handle_fetch_and_analyze_release(properties)).await
     }
 
+    #[tool(
+        description = "List all available Polkadot SDK releases from the polkadot-sdk repository. Helps discover valid release identifiers before using other tools."
+    )]
+    pub(crate) async fn list_polkadot_releases(&self) -> Result<CallToolResult, McpError> {
+        catch_panic_as_mcp_error(tools::handle_list_polkadot_releases()).await
+    }
+
+    // TODO: Support old runtime definition macro
+    #[tool(
+        description = "Find and analyze runtime pallets configured in a given project directory. Scans for #[frame_support::runtime] attributes to discover all pallets used in your runtime(s)."
+    )]
+    pub(crate) async fn find_runtime_pallets(
+        &self,
+        Parameters(properties): Parameters<tools::FindRuntimePalletsProperties>,
+    ) -> Result<CallToolResult, McpError> {
+        catch_panic_as_mcp_error(tools::handle_find_runtime_pallets(properties)).await
+    }
+
     #[tool(
         description = "Use subxt to decode and explore Substrate blockchain data. Useful for: analyzing chain metadata structure, generating type-safe Rust code for chain interactions, exploring available pallets/calls/storage/events, decoding extrinsics and storage values, and understanding runtime APIs. The 'explore' subcommand provides interactive browsing of chain state. Common investigations: System.LastRuntimeUpgrade (find runtime upgrades), Staking.ActiveEra (current era info), Democracy.ReferendumCount (governance activity). Outputs human-readable decoded values by default. Particularly valuable when building applications that need to interact with Substrate chains or when investigating chain functionality. Pass '--help' to any subcommand to learn more."
     )]
@@ -172,6 +191,18 @@ impl SubstrateService {
         prompts::security_review::generate_prompt(args).await
     }
 
+    /// User and agent discussion and issue creation workflow to track PRs in a polkadot release upgrade
+    #[prompt(
+        name = "polkadot_upgrade",
+        description = "User and agent discovery and discussion on what is needed to upgrade polkadot version in your substrate client and runtime"
+    )]
+    async fn polkadot_upgrade(
+        &self,
+        Parameters(args): Parameters<polkadot_upgrade::PolkadotUpgradeArgs>,
+    ) -> Vec<PromptMessage> {
+        prompts::polkadot_upgrade::generate_prompt(args).await
+    }
+
     #[prompt(
         name = "get_started",
         description = "Get started on polkadot and substrate systems"

src/service/mod.rs

@@ -7,6 +7,7 @@
 pub(crate) mod analyze_release;
 pub(crate) mod common;
 pub(crate) mod get_started;
+pub(crate) mod polkadot_upgrade;
 pub(crate) mod release_comparison;
 pub(crate) mod scaffold_pallet;
 pub(crate) mod security_review;