Skip to content

Commit 19f63ac

Browse files
philprimephilprime
committed
docs: Revise README.md for improved structure and clarity
- Enhanced the README layout with centered badges for project status and compatibility. - Added a dedicated "About" section to clarify the purpose of the MCP server. - Expanded the "Use Cases" and "Features" sections for better user guidance. - Included example queries for the `get_action_parameters` and `get_readme` tools. - Removed outdated sections to streamline the document and improve readability.
1 parent ce8b26d commit 19f63ac

File tree

1 file changed

+112
-129
lines changed

1 file changed

+112
-129
lines changed

‎README.md‎

Lines changed: 112 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,122 @@
1-
# GitHub Actions Utils MCP Server
2-
3-
[![GitHub release (latest by date)](https://img.shields.io/github/v/release/techprimate/github-actions-utils-cli?style=flat-square)](https://github.com/techprimate/github-actions-utils-cli/releases/latest)
4-
[![Build Status](https://img.shields.io/github/actions/workflow/status/techprimate/github-actions-utils-cli/build.yml?branch=main&style=flat-square)](https://github.com/techprimate/github-actions-utils-cli/actions/workflows/build.yml)
5-
[![Tests](https://img.shields.io/github/actions/workflow/status/techprimate/github-actions-utils-cli/test.yml?branch=main&style=flat-square&label=tests)](https://github.com/techprimate/github-actions-utils-cli/actions/workflows/test.yml)
6-
[![Go Version](https://img.shields.io/github/go-mod/go-version/techprimate/github-actions-utils-cli?style=flat-square)](https://github.com/techprimate/github-actions-utils-cli/blob/main/go.mod)
7-
[![License](https://img.shields.io/github/license/techprimate/github-actions-utils-cli?style=flat-square)](https://github.com/techprimate/github-actions-utils-cli/blob/main/LICENSE)
8-
[![Docker Image Size](https://img.shields.io/docker/image-size/techprimate/github-actions-utils-cli/latest?style=flat-square)](https://hub.docker.com/r/techprimate/github-actions-utils-cli)
9-
[![Go Report Card](https://goreportcard.com/badge/github.com/techprimate/github-actions-utils-cli?style=flat-square)](https://goreportcard.com/report/github.com/techprimate/github-actions-utils-cli)
10-
[![MCP](https://img.shields.io/badge/MCP-compatible-blue?style=flat-square)](https://modelcontextprotocol.io)
11-
12-
Connect AI tools directly to GitHub Actions. This MCP server gives AI agents, assistants, and chatbots the ability to fetch and analyze GitHub Action definitions, explore available inputs and outputs, and understand action configurations—all through natural language interactions.
13-
14-
### Use Cases
1+
# GitHub Actions Utils MCP Server - Connect AI tools directly to GitHub Actions
2+
3+
<div align="center">
4+
<a href="https://github.com/techprimate/github-actions-utils-cli/releases/latest">
5+
<img src="https://img.shields.io/github/v/release/techprimate/github-actions-utils-cli?style=flat-square" alt="GitHub Release">
6+
</a>
7+
<a href="https://github.com/techprimate/github-actions-utils-cli/actions/workflows/build.yml">
8+
<img src="https://img.shields.io/github/actions/workflow/status/techprimate/github-actions-utils-cli/build.yml?branch=main&style=flat-square" alt="Build Status">
9+
</a>
10+
<a href="https://github.com/techprimate/github-actions-utils-cli/actions/workflows/test.yml">
11+
<img src="https://img.shields.io/github/actions/workflow/status/techprimate/github-actions-utils-cli/test.yml?branch=main&style=flat-square&label=tests" alt="Tests">
12+
</a>
13+
<img src="https://img.shields.io/github/go-mod/go-version/techprimate/github-actions-utils-cli?style=flat-square" alt="Go Version">
14+
<img src="https://img.shields.io/github/license/techprimate/github-actions-utils-cli?style=flat-square" alt="License">
15+
<a href="https://modelcontextprotocol.io">
16+
<img src="https://img.shields.io/badge/MCP-compatible-blue?style=flat-square" alt="MCP Compatible">
17+
</a>
18+
</div>
19+
20+
<div align="center">
21+
<img src="https://img.shields.io/docker/image-size/techprimate/github-actions-utils-cli/latest?style=flat-square" alt="Docker Image Size">
22+
<a href="https://goreportcard.com/report/github.com/techprimate/github-actions-utils-cli">
23+
<img src="https://goreportcard.com/badge/github.com/techprimate/github-actions-utils-cli?style=flat-square" alt="Go Report Card">
24+
</a>
25+
</div>
26+
27+
<p align="center">
28+
<sub>Created and maintained by <a href="https://github.com/techprimate">techprimate</a> and all the amazing <a href="https://github.com/techprimate/github-actions-utils-cli/graphs/contributors">contributors</a>.</sub>
29+
</p>
30+
31+
<p align="center">
32+
<a href="#features">Features</a>
33+
• <a href="#tools">Tools</a>
34+
• <a href="#installation">Installation</a>
35+
• <a href="#configuration">Configuration</a>
36+
• <a href="#example-workflows">Examples</a>
37+
• <a href="#development">Development</a>
38+
• <a href="#license">License</a>
39+
</p>
40+
41+
## About
42+
43+
An MCP (Model Context Protocol) server that gives AI agents, assistants, and chatbots the ability to fetch and analyze GitHub Action definitions, explore available inputs and outputs, and understand action configurations—all through natural language interactions.
44+
45+
**Use Cases:**
1546

1647
- **Workflow Development**: Quickly discover GitHub Action parameters while building CI/CD workflows
1748
- **Action Discovery**: Explore available inputs, outputs, and configuration options for any public GitHub Action
1849
- **Documentation**: Automatically generate documentation for actions used in your workflows
1950
- **Migration & Updates**: Understand parameter changes when upgrading action versions
2051
- **Validation**: Verify action configurations before deploying workflows
2152

22-
Built for developers who want to enhance their AI tools with GitHub Actions context, from simple action queries to complex workflow generation.
53+
## Features
54+
55+
- Fetch GitHub Action parameters (`get_action_parameters` tool)
56+
- Fetch README documentation from GitHub repositories (`get_readme` tool)
57+
- Docker support for easy deployment
58+
- Cross-platform (macOS, Linux, Windows)
59+
- Works with VS Code, Claude Desktop, Cursor, Windsurf, and more
60+
61+
## Tools
62+
63+
### `get_action_parameters`
64+
65+
Fetches and parses a GitHub Action's `action.yml` file, returning complete metadata about inputs, outputs, and configuration.
66+
67+
**Parameters:**
68+
69+
- `actionRef` (required): GitHub Action reference in format `owner/repo@version`
70+
71+
**Example queries:**
72+
73+
```
74+
Can you show me the parameters for actions/checkout@v5?
75+
What inputs does actions/setup-node@v4 accept?
76+
Explain the outputs of docker/build-push-action@v6
77+
```
78+
79+
### `get_readme`
80+
81+
Fetches the README.md file from a GitHub repository for understanding action documentation.
82+
83+
**Parameters:**
84+
85+
- `repoRef` (required): GitHub repository reference in format `owner/repo[@ref]` (defaults to `main` if no ref provided)
86+
87+
**Example queries:**
88+
89+
```
90+
Can you get the README for actions/checkout?
91+
Show me the documentation for docker/build-push-action@v6
92+
What does the README say about github/github-mcp-server?
93+
```
94+
95+
## Example Workflows
96+
97+
**Discovering Action Parameters**
98+
99+
> "What are all the inputs for actions/setup-python@v5?"
100+
101+
AI fetches and explains all available inputs including `python-version`, `cache`, `architecture`, etc.
102+
103+
**Building a Workflow**
104+
105+
> "Help me create a workflow that checks out code, sets up Node.js 20, and runs tests"
106+
107+
AI uses both tools to understand the correct parameters and generate a complete workflow file.
108+
109+
**Comparing Action Versions**
110+
111+
> "What changed between actions/upload-artifact@v3 and @v4?"
112+
113+
AI fetches both versions and highlights the differences in inputs, outputs, and behavior.
114+
115+
**Exploring New Actions**
116+
117+
> "Show me how to use aws-actions/configure-aws-credentials"
118+
119+
AI uses `get_readme` to fetch documentation and `get_action_parameters` to understand all configuration options.
23120

24121
---
25122

@@ -337,120 +434,6 @@ Refer to your MCP client's documentation for the specific configuration file loc
337434

338435
---
339436

340-
## Available Tools
341-
342-
### get_action_parameters
343-
344-
Fetches and parses a GitHub Action's `action.yml` or `action.yaml` file, returning complete metadata about inputs, outputs, and configuration.
345-
346-
**Parameters:**
347-
348-
| Parameter | Type | Required | Description |
349-
| ----------- | ------ | -------- | ---------------------------------------------------------- |
350-
| `actionRef` | string | Yes | GitHub Action reference in the format `owner/repo@version` |
351-
352-
**Examples:**
353-
354-
```
355-
Can you show me the parameters for actions/checkout@v5?
356-
357-
What inputs does actions/setup-node@v4 accept?
358-
359-
Explain the outputs of docker/build-push-action@v6
360-
```
361-
362-
**Response Structure:**
363-
364-
```json
365-
{
366-
"name": "Checkout",
367-
"description": "Checkout a Git repository at a particular version",
368-
"inputs": {
369-
"repository": {
370-
"description": "Repository name with owner. For example, actions/checkout",
371-
"required": false,
372-
"default": "${{ github.repository }}"
373-
},
374-
"ref": {
375-
"description": "The branch, tag or SHA to checkout",
376-
"required": false
377-
},
378-
"token": {
379-
"description": "Personal access token (PAT) used to fetch the repository",
380-
"required": false,
381-
"default": "${{ github.token }}"
382-
}
383-
},
384-
"outputs": {
385-
"ref": {
386-
"description": "The branch, tag or SHA that was checked out"
387-
}
388-
},
389-
"runs": {
390-
"using": "node24",
391-
"main": "dist/index.js"
392-
},
393-
"branding": {
394-
"icon": "download",
395-
"color": "blue"
396-
}
397-
}
398-
```
399-
400-
### get_readme
401-
402-
Fetches the README.md file from a GitHub repository, useful for understanding how to use actions or exploring their documentation.
403-
404-
**Parameters:**
405-
406-
| Parameter | Type | Required | Description |
407-
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
408-
| `repoRef` | string | Yes | GitHub repository reference in the format `owner/repo[@ref]`. If no ref is provided, defaults to `main` |
409-
410-
**Examples:**
411-
412-
```
413-
Can you get the README for actions/checkout?
414-
415-
Show me the documentation for docker/build-push-action@v6
416-
417-
What does the README say about github/github-mcp-server?
418-
```
419-
420-
**Response:**
421-
422-
Returns the full README content as markdown text.
423-
424-
---
425-
426-
## Example Workflows
427-
428-
### Discovering Action Parameters
429-
430-
**User**: "What are all the inputs for actions/setup-python@v5?"
431-
432-
**AI Response**: Uses `get_action_parameters` to fetch and explain all available inputs including `python-version`, `cache`, `architecture`, etc.
433-
434-
### Building a Workflow
435-
436-
**User**: "Help me create a workflow that checks out code, sets up Node.js 20, and runs tests"
437-
438-
**AI**: Uses `get_action_parameters` for `actions/checkout@v5` and `actions/setup-node@v4` to understand the correct parameters and generate a complete workflow file.
439-
440-
### Comparing Action Versions
441-
442-
**User**: "What changed between actions/upload-artifact@v3 and @v4?"
443-
444-
**AI**: Fetches both versions using `get_action_parameters` and highlights the differences in inputs, outputs, and behavior.
445-
446-
### Exploring New Actions
447-
448-
**User**: "Show me how to use aws-actions/configure-aws-credentials"
449-
450-
**AI**: Uses `get_readme` to fetch documentation and `get_action_parameters` to understand all configuration options.
451-
452-
---
453-
454437
## Telemetry
455438

456439
This project uses Sentry for error tracking and performance monitoring to help improve the tool.

0 commit comments

Comments
 (0)