HooksMCP

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 are triggered by MCP functions.
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 which commands agents can run. Validate the arguments agents generate (e.g. ensure a file path is inside the project).
4. Works anywhere MCP works: Cursor, Windsurf, Cline, etc
5. Prompt Library provide access to shared prompts in a standard way. Solves that Cursor/Cline/Codex all have different search paths/filenames.
6. Speed: using MCP unlocks parallel execution, requires fewer tokens for generating commands, and eliminates errors in commands requiring iteration.
7. Collaboration: Check in the YAML file to share with your team.
8. And more: strip ANSI codes/control characters, .env file loading, define required secrets without checking them in, supports exit codes/stdout/stderr, etc

Quick Start

1. Install with uv:

2. Create an hooks_mcp.yaml file in your project root defining your tools and prompts. For example:

3. Run the server:

Running HooksMCP

We recommend running HooksMCP with uvx:

Optional command line arguments include:

• --working-directory/-wd: Typically the path to your project root. Set if not running from project root.
• --disable-prompt-tool: Disable the get_prompt tool entirely, similar to setting get_prompt_tool_filter to an empty array.
• The last argument is the path to the hooks_mcp.yaml file, if not using the default ./hooks_mcp.yaml

Running with Coding Assistants

Cursor

Or open this cursor deeplink.

Windsurf/VSCode/etc

Most other IDEs use a variant of mcp.json. Create an entry for HooksMCP.

Note: Be sure it's run from the root of your project, or manually pass the working directory on startup:

Configuration File Specification

The hooks_mcp.yaml file defines the tools that will be exposed through the MCP server.

See this project's hooks_mcp.yaml as an example.

Top-level Fields

• server_name (optional): Name of the MCP server (default: "HooksMCP")
• server_description (optional): Description of the MCP server (default: "Project-specific development tools and prompts exposed via MCP")
• actions (optional): Array of action definitions. If not provided, only prompts will be available.
• prompts (optional): Array of prompt definitions
• get_prompt_tool_filter (optional): Array of prompt names to expose via the get_prompt tool. If unset, all prompts are exposed. If empty, the get_prompt tool is not exposed.

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)

Action 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.
  • insecure_string: Any string from the model. No validation. Use with caution.
  • required_env_var: An environment variable that must be set before the server starts.
  • optional_env_var : An optional environment variable. Not specified by the calling model.
• description (optional): description of the parameter
• default (optional): Default value for the parameter if not passed

Tool Parameter Examples

project_file_path

This parameter type ensures security by validating that the path parameter is within the project boundaries:

insecure_string

Allows any string input from the agent without validation. Use with caution:

required_env_var

This is a tool parameter expected to exist as an environment variable. The server will fail to start if the environment is missing this var.

This is useful for specifying that a secret (e.g., API key) is needed, without checking the value into your repository. Typically set up when you configure your MCP server (in mcp.json and similar). When trying to set up the MCP server, it will output a user‑friendly message informing the user they need to add the env var to continue.

HooksMCP will load env vars from the environment, and any set in a .env file in your working directory.

This cannot be passed by the calling model.

optional_env_var

Similar to required_env_var but optional. The server will not error on startup if this is missing.

Prompt Fields

HooksMCP can be used to share prompts. For example, a "test_guide" prompt explaining preferred test libraries and best practices for tests.

Each prompt in the prompts array can have the following fields:

• name (required): Unique identifier for the prompt (max 32 characters)
• description (required): description of what the prompt does (max 256 characters)
• prompt (optional): Inline prompt text content. Either prompt or prompt-file must be specified.
• prompt-file (optional): Relative path to a file containing the prompt text content. Either prompt or prompt-file must be specified.
• arguments (optional): Definitions of each argument used in the prompt.

Prompt Argument Fields

Each argument in a prompt's arguments array can have the following fields:

• name (required): The argument name
• description (optional): description of the argument
• required (optional): Boolean indicating if the argument is required (default: false)

To add a prompt in your template, include it in double curly brackets: {{CODE_SNIPPET}}

Prompt Examples

Prompts can be defined inline or loaded from files:

How Prompts are Exposed via MCP

The MCP protocol supports prompts natively; HooksMCP will provide prompts through the official protocol.

However, many clients only support MCP for tool calls. They either completely ignore prompts, or only expose prompts via a dropdown requiring manual human selection. For these clients, we also expose a MCP tool called get_prompt. This tool automatically enabled when prompts are defined, allowing coding agents to retrieve prompt content by name. Note: the get_prompt tool does not support argument substitution. The model will have to infer how to use the prompt from it's template.

To disable the get_prompt tool you can set:

1. Use the --disable-prompt-tool CLI argument. This is local to each user.
2. set get_prompt_tool_filter in the yaml to limit which prompts are exposed, with an empty list disabling the tool. This is for all users.

Security Features

Security Benefits

HooksMCP 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 hooks_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.
4. 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 HooksMCP:

1. If your agent can edit your hooks_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. HooksMCP 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. The first draft was written by Qwen-Coder-405b, and then it was edited by me. See the initial commit for the prompt.

License

MIT