hooks-mcp 0.1.0__tar.gz

hooks_mcp-0.1.0/.github/workflows/all-checks.yml

@@ -0,0 +1,35 @@
+name: All Checks
+
+on:
+  push:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      
+    - name: Install the latest version of uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        enable-cache: true
+
+    - name: Set up Python
+      run: uv python install
+      
+    - name: Install dependencies
+      run: uv sync --all-extras --dev
+      
+    - name: Run all tests
+      run: uv run python -m pytest ./tests/
+      
+    - name: Run linter
+      run: uvx ruff check --extend-select I,F401
+      
+    - name: Check formatting
+      run: uvx ruff format --check .
+      
+    - name: Run type checker
+      run: uv run pyright .

hooks_mcp-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+sketch.sh
+__pycache__/
+find/

hooks_mcp-0.1.0/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+  "python.testing.pytestArgs": [
+    "tests"
+  ],
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestEnabled": true
+}

hooks_mcp-0.1.0/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2025 Steve Cosman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

hooks_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: hooks-mcp
+Version: 0.1.0
+Summary: MCP server that exposes project-specific development tools (tests, linters, etc.) via YAML configuration
+Author: Steve Cosman
+License-Expression: MIT
+License-File: LICENSE.txt
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+      <img width="310" height="65" alt="actionsMCP" src="https://github.com/user-attachments/assets/d5cddfe2-8a7f-4cfb-881f-efae085c35e9" />
+  </picture>
+</p>
+<h3 align="center">
+  MCP server that exposes project-specific development tools (tests, linters, etc.) via a YAML configuration
+</h3>
+
+## Overview
+
+1. **Simple setup:** one YAML file is all it takes to create a custom MCP server for your coding agents. Similar to package.json scripts or Github Actions workflows, but commands run as MCP server functions. Add the YAML to your repo to share with your team.
+2. **Tool discovery:** coding agents know which dev-tools are available and the exact arguments they require. No more guessing CLI strings.
+3. **Improved security:** limit the commands agents can run without approval. Add extra validation of the arguments agents generate (e.g. ensure a file path exists inside the project).
+4. **Works anywhere MCP works:** Cursor, Windsurf, Cline, etc
+5. **And more:** strip ANSI codes/control characters, `.env` file loading, define required secrets without checking them in, supports exit codes/stdout/stderr, etc
+
+[![All Checks](https://github.com/scosman/actions_mcp/actions/workflows/all-checks.yml/badge.svg)](https://github.com/scosman/actions_mcp/actions/workflows/all-checks.yml)
+
+## Quick Start
+
+1. Install with [uv](https://docs.astral.sh/uv/concepts/tools/):
+
+```bash
+uv tool install actions-mcp
+```
+
+2. Create an [`actions_mcp.yaml`](#configuration-file-specification) file in your project root defining your tools. For example:
+
+```yaml
+actions:
+  - name: "all_tests"
+    description: "Run all tests in the project"
+    command: "uv run python -m pytest ./tests"
+    
+  - name: "check_format"
+    description: "Check if the source code is formatted correctly"
+    command: "uvx ruff format --check ."
+    
+  - name: "typecheck"
+    description: "Typecheck the source code"
+    command: "uv run pyright ."
+
+  - name: "test_file"
+    description: "Run tests in a specific file or directory"
+    command: "python -m pytest $TEST_PATH"
+    parameters:
+      - name: "TEST_PATH"
+        type: "project_file_path"
+        description: "Path to test file or directory"
+```
+
+3. Run the server:
+
+```bash
+uvx actions-mcp
+```
+
+See [running ActionsMCP](#running-actionsmcp) for more runtime options.
+
+## Configuration File Specification
+
+The `actions_mcp.yaml` file defines the tools that will be exposed through the MCP server.
+
+See this project's [actions_mcp.yaml](./actions_mcp.yaml) as an example.
+
+### Top-level Fields
+
+- `server_name` (optional): Name of the MCP server (default: "ActionsMCP")
+- `server_description` (optional): Description of the MCP server (default: "Project-specific development tools exposed via MCP")
+- `actions` (required): Array of action definitions
+
+### Action Fields
+
+Each action in the `actions` array can have the following fields:
+
+- `name` (required): Unique identifier for the tool
+- `description` (required): Human-readable description of what the tool does
+- `command` (required): The CLI command to execute. May include dynamic parameters like `$TEST_FILE_PATH`.
+- `parameters` (optional): Definitions of each parameter used in the command. 
+- `run_path` (optional): Relative path from project root where the command should be executed. Useful for mono-repos.
+- `timeout` (optional): Timeout in seconds for command execution (default: 60 seconds)
+
+### Parameter Fields
+
+Each parameter in an action's `parameters` array can have the following fields:
+
+- `name` (required): The parameter name to substitute into the command. For example `TEST_FILE_PATH`.
+- `type` (required): One of the following parameter types:
+  - `project_file_path`: A local path within the project, relative to project root. Validated to ensure it's within project boundaries and exists.
+  - `required_env_var`: An environment variable that must be set before the server starts. Not specified by the calling model. 
+  - `optional_env_var`: An optional environment variable. Not specified by the calling model.
+  - `insecure_string`: Any string from the model. No validation. Use with caution.
+- `description` (optional): Human-readable description of the parameter
+- `default` (optional): Default value for the parameter
+
+## Parameter Types Explained
+
+### project_file_path
+
+This parameter type ensures security by validating that paths are within the project boundaries:
+
+```yaml
+- name: "test_file"
+  description: "Run tests in a specific file"
+  command: "python -m pytest $TEST_FILE"
+  parameters:
+    - name: "TEST_FILE"
+      type: "project_file_path"
+      description: "Path to test file"
+      default: "./tests"
+```
+
+The server will validate that `TEST_FILE` is within the project and exists.
+
+### required_env_var
+
+These parameters must be set in the environment before starting the server. If they are not set, the server will fail on startup asking the user to set the variables.
+
+```yaml
+- name: "deploy"
+  description: "Deploy the application"
+  command: "deploy-tool --key=$DEPLOY_KEY"
+  parameters:
+    - name: "DEPLOY_KEY"
+      type: "required_env_var"
+      description: "Deployment key for the service"
+```
+
+ActionMCP will load env vars from the environment, and any set in a `.env` file in your working directory.
+
+### optional_env_var
+
+Similar to `required_env_var` but optional:
+
+```yaml
+- name: "build"
+  description: "Build the application"
+  command: "build-tool"
+  parameters:
+    - name: "BUILD_FLAGS"
+      type: "optional_env_var"
+      description: "Additional build flags"
+```
+
+### insecure_string
+
+Allows any string input from the coding assistant without validation. Use with caution:
+
+```yaml
+- name: "grep_code"
+  description: "Search code for pattern"
+  command: "grep -r $PATTERN src/"
+  parameters:
+    - name: "PATTERN"
+      type: "insecure_string"
+      description: "Pattern to search for"
+```
+
+## Running ActionsMCP
+
+We recommend running ActionsMCP with [uvx](https://docs.astral.sh/uv/concepts/tools/):
+
+```bash
+# Install
+uv tool install actions-mcp
+# Run
+uvx actions-mcp 
+```
+
+Optional command line arguments include:
+ - `--working-directory`/`-wd`: Typically the path to your project root. Set if not running from project root.
+ - The last argument is the path to the `actions_mcp.yaml` file, if not using the default `./actions_mcp.yaml`
+
+### Running with Coding Assistants
+
+#### Cursor
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=ActionsMCP&config=eyJjb21tYW5kIjoidXZ4IGFjdGlvbnMtbWNwIC0td29ya2luZy1kaXJlY3RvcnkgLiJ9)
+
+Or open this [cursor deeplink](cursor://anysphere.cursor-deeplink/mcp/install?name=ActionsMCP&config=eyJjb21tYW5kIjoidXZ4IGFjdGlvbnMtbWNwIC0td29ya2luZy1kaXJlY3RvcnkgLiJ9).
+
+#### Windsurf/VSCode/etc
+
+Most other IDEs use a variant of [mcp.json](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server-to-your-workspace). Create an entry for ActionMCP.
+
+**Note:** Be sure it's run from the root of your project, or manually pass the working directory on startup:
+
+```json
+{
+  "ActionsMCP": {
+    "command": "uvx",
+    "args": [
+      "actions-mcp",
+      "--working-directory",
+      "."
+    ]
+  }
+}
+```
+
+## Security Features
+
+### Security Benefits
+
+ActionsMCP implements several security measures to help improve security of giving agents access to terminal commands:
+
+1. **Allow List of Commands**: Your agents can only run the commands you give it access to in your `actions_mcp.yaml`, not arbitrary terminal commands.
+
+2. **Path Parameter Validation** All `project_file_path` parameters are validated to ensure they:
+   - Are within the project directory
+   - Actually exist in the project
+
+3. **Environment Variable Controls**: 
+   - `required_env_var` and `optional_env_var` parameters are managed by the developer, not the coding assistant. This prevents coding assistants from accessing sensitive variables.
+
+3. **Safe Command Execution**:
+   - Uses Python `subprocess.run` with `shell=False` to prevent shell injection
+   - Uses `shlex.split` to properly separate command arguments
+   - Implements timeouts to prevent infinite running commands
+
+### Security Risks
+
+There are some risks to using ActionsMCP:
+
+1. If your agent can edit your `actions_mcp.yaml`, it can add commands which it can then run via MCP
+ 
+2. If your agent can add code to your project and any of your actions will invoke arbitrary code (like a test runner), the agent can use this pattern to run arbitrary code
+
+3. ActionMCP may contain bugs or security issues
+
+We don't promise it's perfect, but it's probably better than giving an agent unfettered terminal access. Running inside a container is always recommended for agents.
+
+## Origin Story
+
+I built this for my own use building [Kiln](https://getkiln.ai). The first draft was written by Qwen-Coder-405b, and then it was edited by me. See the [initial commit](https://github.com/scosman/actions_mcp/commit/62fdd5917a1469b64e9dbad73fd713cb0f2454a5) for the prompt.
+
+## License
+
+MIT

hooks_mcp-0.1.0/README.md

@@ -0,0 +1,240 @@
+<p align="center">
+  <picture>
+      <img width="310" height="65" alt="actionsMCP" src="https://github.com/user-attachments/assets/d5cddfe2-8a7f-4cfb-881f-efae085c35e9" />
+  </picture>
+</p>
+<h3 align="center">
+  MCP server that exposes project-specific development tools (tests, linters, etc.) via a YAML configuration
+</h3>
+
+## Overview
+
+1. **Simple setup:** one YAML file is all it takes to create a custom MCP server for your coding agents. Similar to package.json scripts or Github Actions workflows, but commands run as MCP server functions. Add the YAML to your repo to share with your team.
+2. **Tool discovery:** coding agents know which dev-tools are available and the exact arguments they require. No more guessing CLI strings.
+3. **Improved security:** limit the commands agents can run without approval. Add extra validation of the arguments agents generate (e.g. ensure a file path exists inside the project).
+4. **Works anywhere MCP works:** Cursor, Windsurf, Cline, etc
+5. **And more:** strip ANSI codes/control characters, `.env` file loading, define required secrets without checking them in, supports exit codes/stdout/stderr, etc
+
+[![All Checks](https://github.com/scosman/actions_mcp/actions/workflows/all-checks.yml/badge.svg)](https://github.com/scosman/actions_mcp/actions/workflows/all-checks.yml)
+
+## Quick Start
+
+1. Install with [uv](https://docs.astral.sh/uv/concepts/tools/):
+
+```bash
+uv tool install actions-mcp
+```
+
+2. Create an [`actions_mcp.yaml`](#configuration-file-specification) file in your project root defining your tools. For example:
+
+```yaml
+actions:
+  - name: "all_tests"
+    description: "Run all tests in the project"
+    command: "uv run python -m pytest ./tests"
+    
+  - name: "check_format"
+    description: "Check if the source code is formatted correctly"
+    command: "uvx ruff format --check ."
+    
+  - name: "typecheck"
+    description: "Typecheck the source code"
+    command: "uv run pyright ."
+
+  - name: "test_file"
+    description: "Run tests in a specific file or directory"
+    command: "python -m pytest $TEST_PATH"
+    parameters:
+      - name: "TEST_PATH"
+        type: "project_file_path"
+        description: "Path to test file or directory"
+```
+
+3. Run the server:
+
+```bash
+uvx actions-mcp
+```
+
+See [running ActionsMCP](#running-actionsmcp) for more runtime options.
+
+## Configuration File Specification
+
+The `actions_mcp.yaml` file defines the tools that will be exposed through the MCP server.
+
+See this project's [actions_mcp.yaml](./actions_mcp.yaml) as an example.
+
+### Top-level Fields
+
+- `server_name` (optional): Name of the MCP server (default: "ActionsMCP")
+- `server_description` (optional): Description of the MCP server (default: "Project-specific development tools exposed via MCP")
+- `actions` (required): Array of action definitions
+
+### Action Fields
+
+Each action in the `actions` array can have the following fields:
+
+- `name` (required): Unique identifier for the tool
+- `description` (required): Human-readable description of what the tool does
+- `command` (required): The CLI command to execute. May include dynamic parameters like `$TEST_FILE_PATH`.
+- `parameters` (optional): Definitions of each parameter used in the command. 
+- `run_path` (optional): Relative path from project root where the command should be executed. Useful for mono-repos.
+- `timeout` (optional): Timeout in seconds for command execution (default: 60 seconds)
+
+### Parameter Fields
+
+Each parameter in an action's `parameters` array can have the following fields:
+
+- `name` (required): The parameter name to substitute into the command. For example `TEST_FILE_PATH`.
+- `type` (required): One of the following parameter types:
+  - `project_file_path`: A local path within the project, relative to project root. Validated to ensure it's within project boundaries and exists.
+  - `required_env_var`: An environment variable that must be set before the server starts. Not specified by the calling model. 
+  - `optional_env_var`: An optional environment variable. Not specified by the calling model.
+  - `insecure_string`: Any string from the model. No validation. Use with caution.
+- `description` (optional): Human-readable description of the parameter
+- `default` (optional): Default value for the parameter
+
+## Parameter Types Explained
+
+### project_file_path
+
+This parameter type ensures security by validating that paths are within the project boundaries:
+
+```yaml
+- name: "test_file"
+  description: "Run tests in a specific file"
+  command: "python -m pytest $TEST_FILE"
+  parameters:
+    - name: "TEST_FILE"
+      type: "project_file_path"
+      description: "Path to test file"
+      default: "./tests"
+```
+
+The server will validate that `TEST_FILE` is within the project and exists.
+
+### required_env_var
+
+These parameters must be set in the environment before starting the server. If they are not set, the server will fail on startup asking the user to set the variables.
+
+```yaml
+- name: "deploy"
+  description: "Deploy the application"
+  command: "deploy-tool --key=$DEPLOY_KEY"
+  parameters:
+    - name: "DEPLOY_KEY"
+      type: "required_env_var"
+      description: "Deployment key for the service"
+```
+
+ActionMCP will load env vars from the environment, and any set in a `.env` file in your working directory.
+
+### optional_env_var
+
+Similar to `required_env_var` but optional:
+
+```yaml
+- name: "build"
+  description: "Build the application"
+  command: "build-tool"
+  parameters:
+    - name: "BUILD_FLAGS"
+      type: "optional_env_var"
+      description: "Additional build flags"
+```
+
+### insecure_string
+
+Allows any string input from the coding assistant without validation. Use with caution:
+
+```yaml
+- name: "grep_code"
+  description: "Search code for pattern"
+  command: "grep -r $PATTERN src/"
+  parameters:
+    - name: "PATTERN"
+      type: "insecure_string"
+      description: "Pattern to search for"
+```
+
+## Running ActionsMCP
+
+We recommend running ActionsMCP with [uvx](https://docs.astral.sh/uv/concepts/tools/):
+
+```bash
+# Install
+uv tool install actions-mcp
+# Run
+uvx actions-mcp 
+```
+
+Optional command line arguments include:
+ - `--working-directory`/`-wd`: Typically the path to your project root. Set if not running from project root.
+ - The last argument is the path to the `actions_mcp.yaml` file, if not using the default `./actions_mcp.yaml`
+
+### Running with Coding Assistants
+
+#### Cursor
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=ActionsMCP&config=eyJjb21tYW5kIjoidXZ4IGFjdGlvbnMtbWNwIC0td29ya2luZy1kaXJlY3RvcnkgLiJ9)
+
+Or open this [cursor deeplink](cursor://anysphere.cursor-deeplink/mcp/install?name=ActionsMCP&config=eyJjb21tYW5kIjoidXZ4IGFjdGlvbnMtbWNwIC0td29ya2luZy1kaXJlY3RvcnkgLiJ9).
+
+#### Windsurf/VSCode/etc
+
+Most other IDEs use a variant of [mcp.json](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server-to-your-workspace). Create an entry for ActionMCP.
+
+**Note:** Be sure it's run from the root of your project, or manually pass the working directory on startup:
+
+```json
+{
+  "ActionsMCP": {
+    "command": "uvx",
+    "args": [
+      "actions-mcp",
+      "--working-directory",
+      "."
+    ]
+  }
+}
+```
+
+## Security Features
+
+### Security Benefits
+
+ActionsMCP implements several security measures to help improve security of giving agents access to terminal commands:
+
+1. **Allow List of Commands**: Your agents can only run the commands you give it access to in your `actions_mcp.yaml`, not arbitrary terminal commands.
+
+2. **Path Parameter Validation** All `project_file_path` parameters are validated to ensure they:
+   - Are within the project directory
+   - Actually exist in the project
+
+3. **Environment Variable Controls**: 
+   - `required_env_var` and `optional_env_var` parameters are managed by the developer, not the coding assistant. This prevents coding assistants from accessing sensitive variables.
+
+3. **Safe Command Execution**:
+   - Uses Python `subprocess.run` with `shell=False` to prevent shell injection
+   - Uses `shlex.split` to properly separate command arguments
+   - Implements timeouts to prevent infinite running commands
+
+### Security Risks
+
+There are some risks to using ActionsMCP:
+
+1. If your agent can edit your `actions_mcp.yaml`, it can add commands which it can then run via MCP
+ 
+2. If your agent can add code to your project and any of your actions will invoke arbitrary code (like a test runner), the agent can use this pattern to run arbitrary code
+
+3. ActionMCP may contain bugs or security issues
+
+We don't promise it's perfect, but it's probably better than giving an agent unfettered terminal access. Running inside a container is always recommended for agents.
+
+## Origin Story
+
+I built this for my own use building [Kiln](https://getkiln.ai). The first draft was written by Qwen-Coder-405b, and then it was edited by me. See the [initial commit](https://github.com/scosman/actions_mcp/commit/62fdd5917a1469b64e9dbad73fd713cb0f2454a5) for the prompt.
+
+## License
+
+MIT

hooks_mcp-0.1.0/actions_mcp.yaml

@@ -0,0 +1,70 @@
+# ActionsMCP Configuration File for use with the actions-mcp repo!
+
+actions:
+  - name: "all_tests"
+    description: "Run all tests in the project"
+    command: "uv run python -m pytest ./tests/"
+    
+  - name: "lint"
+    description: "Lint the source code, checking for errors and warnings"
+    command: "uvx ruff check --extend-select I,F401"
+
+  - name: "lint_fix"
+    description: "Lint the source code, fixing errors and warnings which it can fix. Not all errors can be fixed automatically."
+    command: "uvx ruff check --extend-select I,F401 --fix"
+
+  - name: "check_format"
+    description: "Check if the source code is formatted correctly"
+    command: "uvx ruff format --check ."
+
+  - name: "format"
+    description: "Format the source code"
+    command: "uvx ruff format ."
+    
+  - name: "typecheck"
+    description: "Typecheck the source code"
+    command: "uv run pyright ."
+
+  - name: "test_file"
+    description: "Run tests in a specific file or directory"
+    command: "uv run python -m pytest $TEST_PATH"
+    parameters:
+      - name: "TEST_PATH"
+        type: "project_file_path"
+        description: "Path to test file or directory"
+
+  - name: "test_specific"
+    description: "Run a specific test by name"
+    command: "uv run python -m pytest $TEST_PATH -k $TEST_NAME"
+    parameters:
+      - name: "TEST_PATH"
+        type: "project_file_path"
+        description: "Path to test file or directory"
+        default: "./tests"
+      - name: "TEST_NAME"
+        type: "insecure_string"
+        description: "Name of the test to run"
+    
+  # Example: Command that requires an environment variable. MCP Server will fail to start if the environment variable is not set.
+  # - name: "deploy"
+  #   description: "Deploy the application (requires DEPLOY_KEY environment variable)"
+  #   command: "echo Deploying with key $DEPLOY_KEY"
+  #   parameters:
+  #     - name: "DEPLOY_KEY"
+  #       type: "required_env_var"
+  #       description: "Deployment key for the service"
+    
+  # # Example: Command with optional environment variable. MCP Server will start even if the environment variable is not set.
+  # - name: "build"
+  #   description: "Build the application"
+  #   command: "echo Building application with key $DEPLOY_KEY"
+  #   parameters:
+  #     - name: "DEPLOY_KEY"
+  #       type: "optional_env_var"
+  #       description: "Deployment key for the service"
+    
+  # # Example: Command that runs from a specific directory. Useful for mono-repos.
+  # - name: "docs_check"
+  #   description: "Check documentation"
+  #   command: "echo Checking documentation in the app/webserver directory"
+  #   run_path: "app/webserver"

hooks_mcp-0.1.0/hooks_mcp/__init__.py

@@ -0,0 +1 @@
+"""Actions MCP - An MCP server that exposes project-specific development tools via YAML configuration."""