Hooks

You can run a focused MCP server that exposes your lint, test, build commands and prompts from a single YAML file. This lets coding agents discover available tools, run allowed commands securely, and access shared prompts in a standardized way. It’s fast, safe, and easy to share with your team.

How to use

Use an MCP client to interact with HooksMCP, then run your configured actions and prompts from the same server. You define tools and prompts in a YAML file, start the MCP server, and call the exposed commands through the client. You can restrict which commands run, validate arguments, and fetch prompts when clients only support basic tool calls.

Typical workflow you’ll follow:

• Write a hooks_mcp.yaml file at your project root defining the tools you want to expose and any prompts you share.
• Install the MCP server runtime if needed and start the server.
• From your MCP client (Cursor, Windsurf, Windsurf-like environments, or other MCP clients), request tool runs or retrieve prompts as defined in your YAML.
• Observe command execution results through stdout/stderr and respect configured timeouts.

Key benefits you get:

• Tool discovery: coding agents know which dev-tools are available and the exact arguments they require.
• Security: you control which commands can run and validate input paths to stay inside the project.
• Prompt library: shared prompts are accessible in a standard way, with optional get_prompt support for clients that need it.

How to install

Prerequisites you need:
- A working development environment with a command line.
- A runtime capable of hosting MCP servers (the example uses the uvx runtime).
- A project where you will place the MCP server configuration file.

Step by step install and run flow:

• Install the MCP runtime globally for your environment.
• Install HooksMCP as a tool.
• Start the MCP server with the appropriate command.
• Point your MCP client at the running server and begin querying tools or prompts.

uv tool install hooks-mcp
uvx hooks-mcp --working-directory .

# If you use a specific YAML file, point to it explicitly
uvx hooks-mcp --working-directory . hooks_mcp.yaml

# Optional: disable the prompt tool from the CLI when starting
uvx hooks-mcp --disable-prompt-tool

Configuration and security

Create a file named hooks_mcp.yaml at your project root. Define actions (tools) and prompts, and control how they’re exposed to the MCP clients. You can require certain environment variables, validate file-path parameters, and limit which prompts are accessible.

Top-level fields you can configure in the YAML:

• server_name: Optional name for the MCP server (default: HooksMCP)
• server_description: Optional description (default: Project-specific development tools and prompts exposed via MCP)
• actions: Optional array of tool definitions
• prompts: Optional array of prompt definitions
• get_prompt_tool_filter: Optional list of prompt names to expose via the get_prompt tool. An empty list disables the tool.

For each action you can define:

• name: Unique tool identifier
• description: Human-readable description
• command: The CLI command to execute (may include dynamic parameters like $TEST_PATH)
• parameters: Optional definitions of each parameter used in the command
• run_path: Optional relative path from project root where the command should execute
• timeout: Optional execution timeout in seconds (default 60)

Parameter types you can use:

• project_file_path: Ensures the path is within the project boundaries and exists
• insecure_string: Any string input from the model with no validation
• required_env_var: Environment variable that must be set to run
• optional_env_var: Optional environment variable that does not block startup

Prompts can be inline or loaded from files. You can reference prompt content in templates using placeholders like {{CODE_SNIPPET}}. The get_prompt tool can retrieve prompt content by name if enabled.

Troubleshooting and notes

If you run into startup errors, check that required environment variables are set, and verify that all project_file_path parameters resolve inside your project. Ensure the server runs from the project root or specify the correct working directory on startup. If a client cannot access prompts, verify the get_prompt_tool_filter and whether the prompt tool was disabled via the CLI flag.

Example configuration and usage

server_name: HooksMCP
server_description: Project-specific development tools and prompts exposed via MCP

actions:
  - name: "all_tests"
    description: "Run all tests in the project"
    command: "uv run python -m pytest ./tests"
    parameters:
      - name: "TEST_PATH"
        type: "project_file_path"
        description: "Path to test file or directory"
        default: "./tests"

prompts:
  - name: "test_guide.md"
    description: "Guide for testing best practices in this library"
    prompt-file: "agents/test_guide.md"

Available tools

get_prompt

Retrieve prompt content by name for clients that expose prompts via MCP when the prompt tool is enabled.