# mcp-ready-mix

> ⚠️ **Heavy Development Warning**: This project is under active development. Use at your own risk. Breaking changes may occur without notice. Fix the tag you are working with by adding `#vMajor.Minor.Patch` to the end of the github repo name in your `.mcp.json` config.

A **Model Context Protocol (MCP)** server that solves the permission fatigue problem with Claude Code.

## The Problem

When using Claude Code, you often need to run the same commands repeatedly (like tests, builds, or deployments). Claude asks for permission every single time, even for commands you've already approved. This quickly becomes tedious.

## The Solution

Ready-mix lets you pre-approve a list of commands by adding them to a `commands.json` file. Claude can then run these commands without asking for permission each time.

## Tools Provided

This server provides 5 tools, all validated with Zod schemas:

- `list_commands` → lists all configured commands with their indices
- `run_command` → executes a specific command by its index number
- `run_command_with_args` → executes a command with arguments using placeholder substitution
- `get_version` → returns the version from `package.json`  
- `echo` → echoes back a required `text` string  

---

## requirements

- Node.js 18+
- macOS/Linux (uses `$SHELL`, defaults to `/bin/bash`)

---

## install

```bash
git clone https://github.com/yourname/mcp-ready-mix.git
cd mcp-ready-mix
npm install
```

---

## local test

### Single command:
```bash
echo '{"commands":[{"cmd":"ls -la","instructions":"List directory contents"}]}' > commands.json && MCP_COMMANDS_FILE="./commands.json" node server.mjs
```

### From commands file:
```bash
MCP_COMMANDS_FILE="./commands.json" node server.mjs
```

This will print a startup line and wait for an MCP client.  

For a quick smoke test of the echo logic:

```bash
node -e 'import("./server.mjs");'   # starts server, but you need an MCP client
```

---

## use with claude code

### 1. Create your commands file

Create a `commands.json` file in your project root with this structure:

```json
{
  "commands": [
    {
      "cmd": "npm test",
      "instructions": "Run all tests"
    },
    {
      "cmd": "npm run build",
      "instructions": "Build the project for production"
    },
    {
      "cmd": "npm run lint",
      "instructions": "Run linter to check code style"
    },
    {
      "cmd": "git status",
      "instructions": "Show git working tree status"
    },
    {
      "cmd": "git log --oneline -10",
      "instructions": "Show last 10 commits in compact format"
    },
    {
      "cmd": "python manage.py test",
      "instructions": "Run Django tests"
    },
    {
      "cmd": "git checkout {0}",
      "instructions": "Checkout git branch"
    },
    {
      "cmd": "npm test {0}",
      "instructions": "Run tests on specific file"
    },
    {
      "cmd": "grep -r {0} {1}",
      "instructions": "Search for pattern in directory"
    }
  ]
}
```

### 2. Add to your .mcp.json

Add this configuration to your `.mcp.json` file:

```json
{
  "mcpServers": {
    "ready-mix": {
      "command": "npx",
      "args": ["-y", "github:Ivor/mcp-ready-mix", "mcp-ready-mix"],
      "env": {
        "MCP_COMMANDS_FILE": "/path/to/your/project/commands.json"
      }
    }
  }
}
```

**Important**: Replace `/path/to/your/project/commands.json` with the actual absolute path to your commands file.

The `instructions` field is optional but helpful for documenting what each command does.  

---

## Usage Examples

### Adding/Updating Commands

To add new commands, simply edit your `commands.json` file:

```json
{
  "commands": [
    {
      "cmd": "npm test",
      "instructions": "Run all tests"
    },
    {
      "cmd": "npm run build",
      "instructions": "Build the project"
    },
    {
      "cmd": "npm run lint",
      "instructions": "Check code style"
    },
    {
      "cmd": "git status",
      "instructions": "Show git status"
    },
    {
      "cmd": "python manage.py migrate",
      "instructions": "Run Django migrations"
    },
    {
      "cmd": "docker-compose up -d",
      "instructions": "Start services in background"
    }
  ]
}
```

Changes are picked up automatically - no restart needed.

### Commands with Arguments

You can create commands that accept arguments using placeholder syntax `{0}`, `{1}`, etc:

```json
{
  "commands": [
    {
      "cmd": "git checkout {0}",
      "instructions": "Checkout git branch"
    },
    {
      "cmd": "npm test {0}",
      "instructions": "Run tests on specific file"
    },
    {
      "cmd": "grep -r {0} {1}",
      "instructions": "Search for pattern in directory"
    },
    {
      "cmd": "find {0} -name {1}",
      "instructions": "Find files by name in directory"
    }
  ]
}
```

Use the `run_command_with_args` tool to execute these commands:
- Command: `git checkout {0}` with args: `["main"]` → executes `git checkout 'main'`
- Command: `grep -r {0} {1}` with args: `["TODO", "src/"]` → executes `grep -r 'TODO' 'src/'`

Arguments are automatically shell-escaped for security.

### Example Claude Interactions

Once configured, you can ask Claude:

- `List the ready-mix commands` → shows all available commands
- `Run command 1` → runs the first command (npm test)
- `Run command 3` → runs the third command (npm run lint)
- `Please run the build command` → Claude will find and run your build command

For commands with arguments:
- `Run command 7 with args main` → runs git checkout with "main" branch
- `Run command 8 with args tests/unit.test.js` → runs npm test on specific file
- `Run command 9 with args TODO and src/` → searches for "TODO" in src/ directory

### Typical Workflow

1. Add commonly used commands to `commands.json`
2. Ask Claude to run tests, builds, or other tasks
3. Claude runs them instantly without asking for permission
4. No more repetitive "Allow this command?" prompts!

---

## Best Way to Test

The most effective way to test this tool is to install it in a real project and use the commands during actual development work. Set up a `commands.json` file with your most common development tasks (tests, builds, linting, git operations) and let Claude run them as you build your project. This gives you the true experience of permission-free command execution and helps identify which commands are most valuable for your workflow.

---

## versioning

1. bump version in `package.json`:
   ```bash
   npm version patch
   git push && git push --tags
   ```
2. update `.mcp.json` args to the new tag or keep `#main` if you want latest.

---

## license

MIT