mcp-makefile-server
Allows exposing Makefile targets as MCP tools, enabling AI agents to execute project-specific build, test, deploy, and other automation tasks defined in a Makefile.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-makefile-serverrun the build target"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Makefile Server
Use this MCP server to easily expose Makefile targets as MCP tools. Let AI agents execute your Makefile targets through the Model Context Protocol.
Table of Contents
Related MCP server: npm-run-mcp-server
What is the Value of mcp-makefile-server?
Value | What you get (benefit) | Why it matters in practice |
Turn your workflow into tools instantly | Anything you can run from a Makefile: scripts, CLIs, one-liners, pipelines, etc. become a first-class MCP tool | You stop “rewriting tooling” for every assistant/client and just expose what already works |
Tooling without building a tool platform | An MCP server that “just works” off your existing Make targets | You avoid bespoke MCP coding, schemas, and glue logic because your Makefile is the integration layer |
No need to remind the coding tool about the Makefile | The coding tool doesn't need to know about the Makefile, it finds out what tools it has automatically via MCP. | You can simply add new targets to the Makefile and the coding tool will automatically know about them. |
Self-service automation | Your assistant can add/adjust targets as needs evolve (you review + merge like normal code) | Tooling grows at the speed of your project |
One source of truth for “how we do things” | The Makefile becomes the canonical catalog of project actions (build, test, lint, release, migrate, etc.) | No drift between docs, tribal knowledge, CI steps, etc. |
Safer execution by design | You expose only what you want (allowlists, internal/skip markers) and keep dangerous stuff hidden | Only give the coding tool access to what it needs to do its job |
Better guidance at the point of use |
| The “how to use it” travels with the command, so it stays accurate as the target evolves |
Composable building blocks | Targets can depend on other targets (e.g., | You get a clean, modular automation graph |
Tooling portability | Makefiles work almost everywhere; you’re not locked into a specific agent ecosystem | Your automation survives client churn. New assistant? Same Make targets |
Features
Feature | Description |
Automatic Tool Discovery | Parses Makefile and exposes documented targets as MCP tools |
Target Filtering | Use allowlists to control which targets are exposed |
Progress Notifications | MCP clients receive start/completion status updates for long-running targets |
Category Support | Organize targets with |
Internal Targets | Mark targets with |
Async Execution | Non-blocking target execution with timeout support |
Output Management | Optional truncation, file output with organized subdirectories, customizable temp location |
Configurable Timeouts | Set custom timeout per target execution (default: 300s) |
TL;DR - Simplest Setup
In your project directory with a Makefile:
# Install uv (if needed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Add MCP server to your project
claude mcp add-json --scope project makefile-server '{
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/ccollicutt/mcp-makefile-server",
"mcp-makefile-server",
"./Makefile"
]
}'
# Restart Claude CodeDone! Your Makefile targets with ## comments are now available as tools.
Usage Patterns
Project-Scoped vs Global Configuration
Recommended: Project-Scoped
The best way to use this MCP server is to point it at your current project's Makefile using --scope project. This approach:
Gives Claude Code access to project-specific targets
Keeps each project's automation isolated and relevant
Allows different projects to have different Makefile targets
Alternative: Global Configuration
You can use --scope global to make the server available across all projects. This is useful if you have:
A shared utilities Makefile with common tasks
Cross-project tooling that you want available everywhere
Both Configurations
You can configure both a global instance and project-specific instances:
Global instance: Points to a shared utilities Makefile (
~/makefiles/common.mk)Project instances: Each project points to its own
./Makefile
Each instance can point to a different Makefile and expose different targets. The global instance provides shared tools, while project instances provide project-specific automation.
Quick Start
Prerequisites
Install uv (if you don't have it):
curl -LsSf https://astral.sh/uv/install.sh | shThis gives you both uv and uvx commands.
Installation Method 1: Using uvx (Recommended)
No cloning needed! uvx runs directly from GitHub:
# Test it works - preview your Makefile targets
uvx --from git+https://github.com/ccollicutt/mcp-makefile-server mcp-makefile-server preview ./MakefileWhat this does:
Downloads and caches the server from GitHub
Runs the
previewcommand on your./MakefileShows what tools would be exposed
Example output:
Found 3 targets in ./Makefile:
• test - Run test suite
• build - Build package
• deploy - Deploy to productionThat's it! Now skip to Claude Code Setup below.
Installation Method 2: Local Installation
Use this if you need to modify the code.
Step 1: Clone and install
git clone https://github.com/ccollicutt/mcp-makefile-server.git
cd mcp-makefile-server
uv pip install .Step 2: Test it works
# Preview your Makefile targets
uv run python -m mcp_makefile preview /path/to/your/Makefile
# Or just list tool names
uv run python -m mcp_makefile list /path/to/your/MakefileFor Development: See DEVELOP.md for development setup instructions.
Claude Code Setup
Configure the MCP server for your project:
If you used Method 1 (uvx):
cd ~/projects/my-app
claude mcp add-json --scope project makefile-server '{
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/ccollicutt/mcp-makefile-server",
"mcp-makefile-server",
"./Makefile"
]
}'If you used Method 2 (local installation):
cd ~/projects/my-app
claude mcp add-json --scope project makefile-server '{
"type": "stdio",
"command": "uv",
"args": [
"--directory",
"/path/to/mcp-makefile-server",
"run",
"python",
"-m",
"mcp_makefile",
"./Makefile"
]
}'What this does:
Creates
.mcp.jsonin your project root (project-scoped)Configures Claude Code to use your Makefile targets as tools when working in this project
For global setup (available in all projects):
Replace --scope project with --scope global in the commands above. This creates a global MCP configuration, though project-scoped is recommended since each project typically has its own Makefile with project-specific targets.
You can configure both: A global instance for shared utilities and project-specific instances for each project's Makefile.
Next step: Restart Claude Code to load the server.
Advanced Configuration
Allowed Targets Filter
Restrict which targets can be executed:
Using uvx:
claude mcp add-json --scope project makefile-server '{
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/ccollicutt/mcp-makefile-server",
"mcp-makefile-server",
"./Makefile",
"--allowed-targets",
"test",
"build",
"lint"
]
}'Using local installation:
claude mcp add-json --scope project makefile-server '{
"type": "stdio",
"command": "uv",
"args": [
"--directory",
"/path/to/mcp-makefile-server",
"run",
"python",
"-m",
"mcp_makefile",
"./Makefile",
"--allowed-targets",
"test",
"build",
"lint"
]
}'Defaults
The server works out of the box with sensible defaults:
Setting | Default Value | What it means |
Output Length | Unlimited ( | All output is returned without truncation |
File Output | Disabled | Output is not written to files (only returned in response) |
Temp Directory |
| Where temporary files are created (if file output is enabled) |
Timeout | 300 seconds | Maximum execution time per target |
Allowed Targets | All non-internal | All targets with |
Log Level |
| Standard logging verbosity |
In other words: The server returns all output directly to the client with no truncation or file writing, executes any documented target, and times out after 5 minutes.
Environment Variables
The server can also be configured via environment variables:
Environment Variable | Description | Default |
| Path to Makefile |
|
| Logging level (DEBUG, INFO, WARNING, ERROR) |
|
| Comma-separated list of allowed targets | All non-internal targets |
| Maximum characters to return from target output (0 = unlimited) |
|
| Write full output to temporary files (true/false) |
|
| Base directory for temporary files |
|
Using environment variables in Claude Code:
You can set environment variables in your .mcp.json configuration:
claude mcp add-json --scope project makefile-server '{
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/ccollicutt/mcp-makefile-server",
"mcp-makefile-server",
"./Makefile"
],
"env": {
"MCP_MAKEFILE_LOG_LEVEL": "DEBUG",
"MCP_MAKEFILE_MAX_OUTPUT_CHARS": "5000",
"MCP_MAKEFILE_WRITE_TO_FILE": "true",
"MCP_MAKEFILE_TEMP_DIR": "/var/tmp"
}
}'This configures the server to:
Use DEBUG logging
Truncate output at 5000 characters
Write full output to files in
/var/tmp/mcp-makefile-{random-id}/
See Claude Code Settings Documentation for more information.
Setting environment variables in your shell:
export MCP_MAKEFILE_PATH=/path/to/Makefile
export MCP_MAKEFILE_LOG_LEVEL=DEBUG
export MCP_MAKEFILE_ALLOWED_TARGETS="test,build,lint"
export MCP_MAKEFILE_MAX_OUTPUT_CHARS=5000
export MCP_MAKEFILE_WRITE_TO_FILE=true
export MCP_MAKEFILE_TEMP_DIR=/var/tmpOutput Management
The server provides two options for managing large output:
Option 1: Truncate Output (Optional)
By default, output is unlimited. To prevent token overload, you can enable truncation:
Via environment variable:
export MCP_MAKEFILE_MAX_OUTPUT_CHARS=5000 # Set >0 to truncate, 0 = unlimitedVia command-line argument:
mcp-makefile-server serve ./Makefile --max-output-chars 5000When output is truncated, you'll see a message like:
Note: Output exceeded 5000 characters and was truncated.
Configure targets to log verbose output to files and return summaries instead.Option 2: Write to Temporary File
Write full output to temporary files and return the file path. The server creates a unique subdirectory for each session to organize output files.
Via environment variable:
export MCP_MAKEFILE_WRITE_TO_FILE=trueVia command-line argument:
mcp-makefile-server serve ./Makefile --write-to-fileWhen enabled, you'll see:
Full output written to: /tmp/mcp-makefile-4a3f2e1b/test-1234567890.logCustomize temp directory location:
# Via environment variable
export MCP_MAKEFILE_TEMP_DIR=/var/tmp
# Via command-line argument
mcp-makefile-server serve ./Makefile --write-to-file --temp-dir /var/tmpThe server automatically creates a randomized subdirectory (e.g., mcp-makefile-{random-id}) within the temp directory to organize all output files for that session.
You can combine both options to truncate the returned output while keeping a full copy in a file.
Removing and Uninstalling
Remove from Claude Code
To remove the MCP server from your project:
cd ~/projects/my-app
claude mcp remove "makefile-server" -s projectThis removes the server from .mcp.json. Restart Claude Code to apply changes.
Uninstall the Server
If you used Method 1 (uvx):
The server is cached automatically. To clear it:
# Clear specific package from cache
uv cache clean mcp-makefile-server
# Or clear entire uv cache
uv cache cleanIf you used Method 2 (local installation):
# Uninstall the package
uv pip uninstall mcp-makefile-server
# Optionally, remove the cloned directory
rm -rf /path/to/mcp-makefile-serverTroubleshooting
Connection Failed
If Claude Code shows "Failed to reconnect to makefile-server":
Check the command name is
mcp-makefile-server(notmcp-makefile)Verify the Makefile path is correct
Check the server logs: Look at Claude Code's output panel
Test the server manually:
uvx --from git+https://github.com/ccollicutt/mcp-makefile-server mcp-makefile-server preview ./Makefile
Makefile Format
Your Makefile must use the standard self-documenting format with ## comments:
.PHONY: test build deploy
## Category: Testing
test: ## Run test suite with pytest (outputs results to stdout)
pytest
lint: ## Check code style and formatting with ruff (reports issues found)
ruff check .
## Category: Building
build: test ## Build Python package distribution (runs tests first, creates dist/ directory with wheel and sdist)
python -m build
# Mark targets as internal (NOT exposed)
deploy-prod: ## @internal Deploy to production
./deploy.sh --prod
# Regular targets ARE exposed
deploy-staging: test ## Deploy to staging environment (runs tests first, creates deploy.log)
./deploy.sh --stagingFormat Rules:
Target Type | Result |
Targets with | Exposed as MCP tools |
Targets with | NOT exposed |
Targets without | Ignored |
Development
For development setup, testing, Python API usage, and contributing guidelines, see DEVELOP.md.
Best Practices
Efficient Output (Token Usage)
MCP responses consume tokens and bandwidth. Keep output concise:
Good practices:
# Use variables for options, not separate targets
VERBOSE ?= 0
LOG_FILE ?= test-results.log
test: ## Run test suite with pytest (VERBOSE=1 for detailed output, LOG_FILE=path to save results, default: quiet mode with summary)
@echo "Running tests..."
@if [ "$(VERBOSE)" = "1" ]; then \
pytest -v > $(LOG_FILE) 2>&1 && echo "✓ Tests complete (verbose). Full output in $(LOG_FILE)"; \
else \
pytest --quiet --tb=short > $(LOG_FILE) 2>&1 && echo "✓ Tests complete. Full output in $(LOG_FILE)" || \
(echo "✗ Tests failed. Check $(LOG_FILE) for errors" && exit 1); \
fi
build: ## Build Python package distribution (creates dist/ with wheel and sdist, full output saved to build.log)
@echo "Building package..."
@python -m build --quiet > build.log 2>&1 && echo "✓ Build complete. See build.log" || \
(echo "✗ Build failed. Check build.log for errors" && exit 1)
lint: ## Check code style with ruff (reports only issues found, use FIX=1 to auto-fix problems)
@if [ "$(FIX)" = "1" ]; then \
ruff check --fix . && echo "✓ Linting complete (auto-fixed)"; \
else \
ruff check . --quiet && echo "✓ No linting issues" || echo "✗ Linting failed"; \
fiAvoid:
# DON'T: Create many similar targets
test: ## Run tests
pytest --quiet
test-verbose: ## Run tests verbosely
pytest -vvv # Separate target for same thing!
test-coverage: ## Run tests with coverage
pytest --cov # Another target!
# DON'T: Poor descriptions
build: ## Build # What does it build? What are the options?
python -m build
# DON'T: Print everything
deploy: ## Deploy
npm install # Prints hundreds of lines
npm run build # Prints more lines
kubectl apply -f . # Even more outputDescription Best Practices:
The ## description is sent to the MCP client/AI, so make it informative:
# GOOD: Clear description with options explained
test: ## Run test suite (VERBOSE=1 for details, TEST=pattern to filter, COVERAGE=1 for coverage report)
...
# GOOD: Explains what it does and what happens
deploy-staging: ## Deploy to staging environment (runs tests first, creates deploy.log with details)
...
# BAD: Too vague
test: ## Test
...
# BAD: Missing important info
deploy: ## Deploy
...Tips:
Tip | Description | Example |
Write AI-friendly descriptions | Use human-readable comments ( |
|
Mark helper targets as internal | Sub-functions and helpers the AI doesn't need should be marked |
|
Use variables, not multiple targets | Pass options via variables instead of creating separate targets |
|
Write clear descriptions | Explain what it does and what options are available | See Description Best Practices above |
Log verbose output to files | Commands that produce lots of output should log to a file and return only a summary to avoid overloading tokens |
|
Use | Suppress command echo to reduce output noise |
|
Use | Use quiet flags when available |
|
Redirect to log files | Save verbose output for later analysis |
|
Print concise summaries | Show brief success/failure instead of full output |
|
Combine redirect + summary | Redirect full output to file, then echo summary message |
|
Exit codes matter | Return non-zero on failure for AI to detect errors | Always preserve exit codes |
Examples
See tests/fixtures/ for example Makefiles:
File | Description |
| Basic targets |
| With category organization |
| Shows internal targets and filtering |
License
MIT License
Available Tools
12 toolscheckB
Run all static checks and security scans (depends on: format, lint, type-check, security-scan)
| Name | Required | Description | Default |
|---|---|---|---|
| variables | No | Make variables to pass (e.g., {'DEBUG': '1'}) | |
| timeout | No | Timeout in seconds (default: 300, max recommended: 3600) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must carry the full burden. It lists dependencies but does not disclose execution order, failure behavior, side effects, or safety profile. This is insufficient for a composite tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose. Compact but could be expanded slightly without losing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, no annotations, and description omits return values, error handling, or execution model. For a composite run tool, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3 applies. The description adds no additional meaning beyond the schema for variables and timeout; it does not explain their role or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs all static checks and security scans, listing dependencies (format, lint, type-check, security-scan). This distinguishes it from sibling tools like lint or security-scan, which are individual checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when an aggregate check is desired, but does not explicitly state when to use this tool vs. running individual siblings, nor does it mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cleanD
Clean cache files
| Name | Required | Description | Default |
|---|---|---|---|
| variables | No | Make variables to pass (e.g., {'DEBUG': '1'}) | |
| timeout | No | Timeout in seconds (default: 300, max recommended: 3600) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It does not indicate whether the operation is destructive, safe, or has side effects. The phrase 'clean cache files' gives no insight into what actually happens (e.g., deletion, invalidation).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise (3 words) but at the expense of clarity. For a tool with two parameters, one a nested object, this is under-specification. Not all concise descriptions are effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and the description fails to explain what cleaning cache entails, expected outcomes, or warnings. With moderate complexity (2 params, nested object), this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both parameters have descriptions). The tool description adds no new meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description 'Clean cache files' states verb and resource but is vague. It does not specify what kind of cache (e.g., build cache, dependency cache) or how it differs from sibling tools like 'format' or 'lint' that might also involve maintenance tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs siblings. No mention of prerequisites, when-not-to-use, or alternatives. Sibling tools include 'check', 'format', 'lint', etc., but no context is provided to help an agent decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
formatC
Format code with ruff
| Name | Required | Description | Default |
|---|---|---|---|
| variables | No | Make variables to pass (e.g., {'DEBUG': '1'}) | |
| timeout | No | Timeout in seconds (default: 300, max recommended: 3600) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose whether the tool modifies files in place, requires a config, or has any side effects. The behavior of 'format with ruff' is ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence) but lacks structure and important details, making it under-specified despite being short.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It does not cover return format, safety, or prerequisites for a formatting tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional information about the parameters beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it formats code using ruff, which is a specific verb and resource. However, it does not differentiate from sibling tools like 'lint' or 'check' which also focus on code quality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool compared to alternatives, nor any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
helpC
Show available targets
| Name | Required | Description | Default |
|---|---|---|---|
| variables | No | Make variables to pass (e.g., {'DEBUG': '1'}) | |
| timeout | No | Timeout in seconds (default: 300, max recommended: 3600) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose behavioral traits such as read-only nature, network requirements, or side effects. For a help tool, the behavior is largely implied but not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks structure and critical information. For a simple tool, it is adequate but not exemplary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, and a low-complexity tool, the description should explain what 'targets' are, provide example usage, or mention how to interpret results. It fails to do so, leaving gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema description coverage is 100%, the description adds no meaning beyond the parameter names. For example, 'variables' and 'timeout' are defined in schema but their role in the help context (e.g., passing variables for dynamic targets) is not explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Show available targets' clearly states the tool's function as a discovery/help tool, listing possible targets. This distinguishes it from sibling tools like 'check', 'lint', etc., which are specific actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives. Lacks context like 'Use this to see available commands before running them' or any mention of prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
lintC
Run ruff linter
| Name | Required | Description | Default |
|---|---|---|---|
| variables | No | Make variables to pass (e.g., {'DEBUG': '1'}) | |
| timeout | No | Timeout in seconds (default: 300, max recommended: 3600) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It only states 'run' but does not indicate whether linting modifies files, requires specific permissions, or has side effects. This is insufficient for a mutation-like action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (three words). While not verbose, it lacks structure or front-loading. A slightly longer line could add context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations or output schema, the description should compensate but does not. It omits what the tool returns (e.g., lint results) and when to use it (e.g., after code changes). The tool is simple but the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both parameters (variables, timeout) are documented in the schema. The description adds no additional meaning beyond the schema, achieving the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Run ruff linter' clearly identifies the verb (run) and the specific tool (ruff linter). It distinguishes from siblings like format or type-check, but could be enhanced by specifying 'Python' to clarify the type of linting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like check or security-scan. The description lacks context on suitable situations or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
releaseA
Create new release with version bump, tests, git tag, and push. Prompts for version type: [p]atch, [m]inor, [M]ajor, or [n]o bump. Use DRY_RUN=1 to preview without making changes
| Name | Required | Description | Default |
|---|---|---|---|
| variables | No | Make variables to pass (e.g., {'DEBUG': '1'}) | |
| timeout | No | Timeout in seconds (default: 300, max recommended: 3600) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden of transparency. It discloses the main steps (version bump, tests, git tag, push) and the interactive prompt for version type, but lacks details on error handling, authentication, or side effects like what happens if tests fail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the main action, no unnecessary words. Efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core release steps but omits details on prerequisites (e.g., clean git status), return values, or error conditions. Given the complexity of a release tool and no output schema, more context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds minimal value beyond the schema, only hinting that 'variables' are make variables. The timeout parameter is already well described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create new release with version bump, tests, git tag, and push.' It specifies the main actions and distinguishes from sibling tools like 'test' or 'version' by mentioning the full release pipeline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use the tool (for creating a release) and includes version bump options and the DRY_RUN tip. However, it does not explicitly state when not to use it or mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
security-scanB
Run security scans (bandit, safety, vulture, pylint)
| Name | Required | Description | Default |
|---|---|---|---|
| variables | No | Make variables to pass (e.g., {'DEBUG': '1'}) | |
| timeout | No | Timeout in seconds (default: 300, max recommended: 3600) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description does not disclose side effects, return values, or permissions needed for running scans.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no redundancy; front-loaded with verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low complexity, the description omits output format, side effects, and fails to compensate for missing annotations and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters; description adds no extra meaning beyond listing scanners.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs security scans and lists specific scanners (bandit, safety, vulture, pylint), distinguishing it from sibling tools like lint or test.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use or avoid this tool vs. siblings; no mention of context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
syncB
Install dependencies and create lockfile
| Name | Required | Description | Default |
|---|---|---|---|
| variables | No | Make variables to pass (e.g., {'DEBUG': '1'}) | |
| timeout | No | Timeout in seconds (default: 300, max recommended: 3600) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks behavioral details such as whether the tool is safe to run repeatedly, if it modifies files (destructive), or any required permissions. Without annotations, this information is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence. Every word adds value, and it is appropriately concise for a simple tool without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately explains the tool's primary function but fails to provide context on when to invoke it (e.g., before testing, after code changes). No output schema exists, so return value information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both 'variables' and 'timeout'. The description does not add extra meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool installs dependencies and creates a lockfile, which is a specific verb+resource pair. It distinguishes from sibling tools like check, lint, or test, which perform different functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., clean, update). The description does not specify prerequisites, post-conditions, or typical workflow context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
testC
Run all tests
| Name | Required | Description | Default |
|---|---|---|---|
| variables | No | Make variables to pass (e.g., {'DEBUG': '1'}) | |
| timeout | No | Timeout in seconds (default: 300, max recommended: 3600) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. 'Run all tests' implies execution but does not mention side effects (e.g., file modifications, network calls), output format, or failure behavior, leaving significant unknowns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (3 words), but at the cost of clarity and completeness. It sacrifices necessary context for brevity, making it borderline too short to be helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of many sibling tools and no output schema, the description is incomplete. It fails to explain what 'all tests' entails, return values, or how it differs from related tools like 'test-coverage'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for both parameters. The tool description adds no extra meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Run all tests' provides a verb and resource, indicating the tool executes tests, but it is vague about the type and scope of tests, especially given siblings like 'test-coverage' and 'lint'. It does not distinguish itself clearly from other testing-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'test-coverage', 'lint', or 'check'. There is no mention of prerequisites, context, or exclusions, leaving the agent to infer usage without support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
test-coverageB
Run tests with coverage report
| Name | Required | Description | Default |
|---|---|---|---|
| variables | No | Make variables to pass (e.g., {'DEBUG': '1'}) | |
| timeout | No | Timeout in seconds (default: 300, max recommended: 3600) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states the high-level action, omitting details about execution time, side effects, output format, or required environment.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core purpose. It is efficient but could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fails to mention what the tool returns (e.g., coverage report location or summary). The 'variables' parameter is an object for make variables, but no context is given. The description is under-specified for a tool with two parameters and nested objects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the schema descriptions for 'variables' and 'timeout', which are already self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Run tests with coverage report' clearly specifies the action (run tests) and the outcome (coverage report). It distinguishes from sibling tools like 'test' which likely runs tests without coverage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not indicate when to use this tool over alternatives like 'test' or 'check', nor any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
type-checkB
Run pyright type checker
| Name | Required | Description | Default |
|---|---|---|---|
| variables | No | Make variables to pass (e.g., {'DEBUG': '1'}) | |
| timeout | No | Timeout in seconds (default: 300, max recommended: 3600) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description does not disclose behavioral traits such as side effects, resource consumption, or mutability. The implied action is running a command, but no further details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise, one short phrase. No wasted words, but could benefit from a touch more context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature (2 params, no output schema), the description is minimally adequate. However, it lacks any mention of output or behavior, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description adds no extra meaning beyond what schema already provides for the two parameters. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Run pyright type checker', specifying the exact tool and its function. It distinguishes from sibling tools like 'lint' or 'check' by focusing on pyright type checking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites, and no conditions for use or avoidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
versionA
Show current version from VERSION file
| Name | Required | Description | Default |
|---|---|---|---|
| variables | No | Make variables to pass (e.g., {'DEBUG': '1'}) | |
| timeout | No | Timeout in seconds (default: 300, max recommended: 3600) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Minimal but accurate description. No annotations provided, so description carries full burden. It indicates a read operation without side effects, lacking details on file location or potential errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key action and resource. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple version retrieval tool, the description is mostly complete. It could specify the expected location of the VERSION file, but the purpose is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline 3 is appropriate. Description adds no additional meaning beyond the schema for the two optional parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the specific action (Show), resource (version), and source (VERSION file). It is distinct from sibling tools like lint, test, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not mention context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
12 tool updates
v0.1.0- First observed
check - First observed
clean - First observed
format - First observed
help - First observed
lint - First observed
release - First observed
security-scan - First observed
sync - First observed
test - First observed
test-coverage - First observed
type-check - First observed
version
TDQS
Scored across 12 tools
Most tools have distinct purposes, but 'check' is a composite that runs format, lint, type-check, and security-scan, which could cause agents to misuse it when only one subtask is needed. Additionally, 'test' and 'test-coverage' overlap; both run tests, with the latter adding coverage.
All tool names follow a consistent pattern: single verbs or hyphenated verb-noun compounds in lowercase (e.g., format, test-coverage, security-scan). No mixing of conventions like camelCase or snake_case.
With 12 tools, the server is well-scoped for a Python development workflow using Makefiles. The number covers essential tasks without being excessive or insufficient.
The tools cover the core development lifecycle: formatting, linting, type checking, security scanning, testing, and release management. Missing a build or deploy step, but these are often outside the scope of a Makefile server for development tasks.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
Free public MCP for AI agents — 193 tools, 44 workflows. No API key.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that exposes Makefile targets as callable tools for AI assistants, allowing Claude and similar models to execute Make commands with provided arguments.MIT
- AlicenseBqualityCmaintenanceExposes your project's package.json scripts as MCP tools, allowing AI assistants to discover and execute npm/yarn/pnpm/bun scripts directly. Automatically detects your package manager and enables running scripts with optional arguments through natural language commands.5423MIT
- FlicenseNot gradedqualityDmaintenanceExposes a set of CLI tools (test generation, documentation generation, linting, test running, code search) to AI assistants via MCP, allowing them to perform these tasks through natural language.3-
- AlicenseNot gradedqualityDmaintenanceExposes Just recipes as MCP tools, allowing AI assistants to discover and execute project commands defined in Justfiles.181MIT