feat: add workflow analysis and update suggestion tools

- Add analyze_workflow tool for version status reporting
- Add suggest_updates tool for safe update recommendations
- Add get_latest_in_major tool for staying within major versions
- Add parse-workflow utility for YAML parsing
- Extend parse-action with version comparison utilities
- Update README with new tool documentation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: mediazone

README.md

@@ -7,6 +7,8 @@ reference GitHub Actions by providing:
 - Commit SHA retrieval for specific version tags
 - Immutability status checking for releases
 - Ready-to-use SHA-pinned references
+- **Workflow analysis** with update level detection (major/minor/patch)
+- **Safe update suggestions** that avoid breaking changes
 
 ## Why Use This?
 
@@ -103,6 +105,9 @@ Once configured, ask Claude to look up GitHub Actions:
 - "Get the secure reference for actions/setup-node@v4"
 - "Check if actions/cache@v4.2.0 is immutable"
 - "List all versions of actions/upload-artifact"
+- "Analyze my workflow file for outdated actions"
+- "Suggest safe updates for my CI workflow"
+- "What's the latest v4.x version of actions/checkout?"
 
 ## Tool: `lookup_action`
 
@@ -118,19 +123,131 @@ Once configured, ask Claude to look up GitHub Actions:
 ```
 Action: actions/checkout
 
-Latest Version: v4.2.2
-  Commit SHA: 11bd71901bbe5b1630ceea73d27597364c9af683
-  Immutable: Yes
-  Published: 2024-10-23T14:05:06Z
+Latest Version: v6.0.1
+  Commit SHA: 8e8c483db84b4bee98b60c0593521ed34d9990e8
+  Immutable: No
+  Published: 2025-12-02T16:38:59Z
 
 Recommended Usage (SHA-pinned):
-  uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+  uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
 Security Notes:
-  - This release is immutable - the tag and assets are protected from modification.
+  - WARNING: This release is NOT immutable. The tag could potentially be moved to a different commit.
+  - Using the SHA-pinned reference provides protection against tag tampering.
   - SHA-pinned references prevent supply chain attacks by ensuring you always use the exact same code.
 ```
 
+## Tool: `analyze_workflow`
+
+Analyze a GitHub Actions workflow file and show version status for all actions.
+Reports current vs latest versions, update levels (major/minor/patch), and risk
+assessment.
+
+### Parameters
+
+| Parameter          | Type    | Required | Description                                          |
+| ------------------ | ------- | -------- | ---------------------------------------------------- |
+| `workflow_content` | string  | Yes      | The workflow YAML content to analyze                 |
+| `only_updates`     | boolean | No       | Only show actions that need updates (default: false) |
+
+### Example Output
+
+```
+## Summary
+Total actions: 6
+Up to date: 1
+Major updates available: 2 ⚠️
+Minor updates available: 2
+Patch updates available: 1
+
+## Actions
+
+| Action | Current | Latest | Update | Risk |
+|--------|---------|--------|--------|------|
+| actions/checkout | v4.2.2 | v6.0.1 | ⚠️ Major | 🔴 High |
+| actions/setup-node | v4.1.0 | v6.2.0 | ⚠️ Major | 🔴 High |
+| docker/login-action | v3.3.0 | v3.6.0 | 📦 Minor | 🟡 Medium |
+| docker/build-push-action | v6.9.0 | v6.18.0 | 📦 Minor | 🟡 Medium |
+| appleboy/ssh-action | v1.2.0 | v1.2.4 | 🔧 Patch | 🟢 Low |
+
+## Safe Updates (Minor/Patch)
+...
+
+## Major Updates (Review Required)
+...
+```
+
+## Tool: `suggest_updates`
+
+Suggest safe updates for GitHub Actions in a workflow. Returns only safe updates
+(minor/patch) and suggestions to stay current within major versions.
+
+### Parameters
+
+| Parameter          | Type   | Required | Description                                                                  |
+| ------------------ | ------ | -------- | ---------------------------------------------------------------------------- |
+| `workflow_content` | string | Yes      | The workflow YAML content to analyze                                         |
+| `risk_tolerance`   | string | No       | `"patch"` = only patches, `"minor"` = patch + minor (default), `"all"` = all |
+
+### Example Output
+
+```
+## Summary
+Total actions analyzed: 6
+Already up to date: 1
+Safe updates available: 3
+Actions with major updates: 2 (staying on current major)
+
+## Safe Updates
+These updates are safe to apply:
+
+### 📦 docker/login-action: v3.3.0 → v3.6.0
+Minor version update - new features, backwards compatible
+
+uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567 # v3.6.0
+
+### 🔧 appleboy/ssh-action: v1.2.0 → v1.2.4
+Patch version update - bug fixes only
+
+uses: appleboy/ssh-action@2ead5e36573714d0d3cfcbac3646c3e0f09ec849 # v1.2.4
+
+## Updates Within Current Major
+These actions have major updates available, but you can safely update within your current major version:
+
+### actions/checkout: v4.2.2 → v4.2.2
+Safe update within v4.x (latest overall is v6.0.1)
+
+uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+```
+
+## Tool: `get_latest_in_major`
+
+Get the latest version of a GitHub Action within the same major version. Useful
+for safe updates that avoid breaking changes.
+
+### Parameters
+
+| Parameter | Type   | Required | Description                                                              |
+| --------- | ------ | -------- | ------------------------------------------------------------------------ |
+| `action`  | string | Yes      | Action reference with version (e.g., `actions/checkout@v4` or `@v4.1.0`) |
+
+### Example Output
+
+```
+Action: actions/checkout
+Current Version: v4
+Major Version: v4
+
+Latest in v4.x: v4.2.2
+  Commit SHA: 11bd71901bbe5b1630ceea73d27597364c9af683
+  Immutable: Yes
+
+Note: Latest overall is v6.0.1
+
+Recommended Usage (SHA-pinned):
+  uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+```
+
 ## Authentication
 
 The service supports multiple authentication methods, checked in the following
@@ -252,10 +369,10 @@ When set, the service will:
 ```
 Action: actions/checkout
 
-Latest Version: v4.2.1
-  Commit SHA: abc123...
-  Immutable: Yes
-  Published: 2024-10-15T10:00:00Z (7 days ago)
+Latest Version: v6.0.1
+  Commit SHA: 8e8c483db84b4bee98b60c0593521ed34d9990e8
+  Immutable: No
+  Published: 2025-12-02T16:38:59Z (52 days ago)
 
 Security Notes:
   - Minimum release age filter active: only considering releases at least 5 days old.

main.ts

@@ -9,6 +9,16 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { formatResultAsText, lookupAction } from "./src/tools/lookup-action.ts";
+import {
+  analyzeWorkflow,
+  formatAnalyzeResultAsText,
+} from "./src/tools/analyze-workflow.ts";
+import {
+  formatLatestInMajorAsText,
+  formatSuggestUpdatesAsText,
+  getLatestInMajorVersion,
+  suggestUpdates,
+} from "./src/tools/suggest-updates.ts";
 
 // Create the MCP server
 const server = new McpServer({
@@ -65,6 +75,144 @@ server.tool(
   },
 );
 
+// Register the analyze_workflow tool
+server.tool(
+  "analyze_workflow",
+  "Analyze a GitHub Actions workflow file and show version status for all actions. " +
+    "Reports current vs latest versions, update levels (major/minor/patch), and risk assessment.",
+  {
+    workflow_content: z
+      .string()
+      .describe("The workflow YAML content to analyze"),
+    only_updates: z
+      .boolean()
+      .optional()
+      .describe("Only show actions that need updates (default: false)"),
+  },
+  async ({ workflow_content, only_updates }) => {
+    try {
+      const result = await analyzeWorkflow({
+        workflow_content,
+        only_updates,
+      });
+      const text = formatAnalyzeResultAsText(result);
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text,
+          },
+        ],
+      };
+    } catch (error) {
+      const message = error instanceof Error
+        ? error.message
+        : "Unknown error occurred";
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Error: ${message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  },
+);
+
+// Register the suggest_updates tool
+server.tool(
+  "suggest_updates",
+  "Suggest safe updates for GitHub Actions in a workflow. " +
+    "Returns only safe updates (minor/patch) and suggestions to stay current within major versions.",
+  {
+    workflow_content: z
+      .string()
+      .describe("The workflow YAML content to analyze"),
+    risk_tolerance: z
+      .enum(["patch", "minor", "all"])
+      .optional()
+      .describe(
+        "Risk tolerance: 'patch' = only patches, 'minor' = patch + minor (default), 'all' = include major",
+      ),
+  },
+  async ({ workflow_content, risk_tolerance }) => {
+    try {
+      const result = await suggestUpdates({
+        workflow_content,
+        risk_tolerance,
+      });
+      const text = formatSuggestUpdatesAsText(result);
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text,
+          },
+        ],
+      };
+    } catch (error) {
+      const message = error instanceof Error
+        ? error.message
+        : "Unknown error occurred";
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Error: ${message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  },
+);
+
+// Register the get_latest_in_major tool
+server.tool(
+  "get_latest_in_major",
+  "Get the latest version of a GitHub Action within the same major version. " +
+    "Useful for safe updates that avoid breaking changes.",
+  {
+    action: z
+      .string()
+      .describe(
+        "Action reference with version, e.g., 'actions/checkout@v4' or 'actions/setup-node@v4.1.0'",
+      ),
+  },
+  async ({ action }) => {
+    try {
+      const result = await getLatestInMajorVersion({ action });
+      const text = formatLatestInMajorAsText(result);
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text,
+          },
+        ],
+      };
+    } catch (error) {
+      const message = error instanceof Error
+        ? error.message
+        : "Unknown error occurred";
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Error: ${message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  },
+);
+
 // Start the server with stdio transport
 async function main() {
   const transport = new StdioServerTransport();