Skip to main content
Glama
ccollicutt
by ccollicutt

MCP Makefile Server

TIP

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

## comments become the tool’s instructions: options, inputs, side effects, outputs

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., build: test lint) and form reliable workflows

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 ## Category: headers

Internal Targets

Mark targets with @internal or @skip to exclude them

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 Code

Done! 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 | sh

This gives you both uv and uvx commands.


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 ./Makefile

What this does:

  • Downloads and caches the server from GitHub

  • Runs the preview command on your ./Makefile

  • Shows what tools would be exposed

Example output:

Found 3 targets in ./Makefile:
  • test - Run test suite
  • build - Build package
  • deploy - Deploy to production

That'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/Makefile

For 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.json in 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 (0)

All output is returned without truncation

File Output

Disabled

Output is not written to files (only returned in response)

Temp Directory

/tmp

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 ## comments are exposed (except @internal/@skip)

Log Level

INFO

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

MCP_MAKEFILE_PATH

Path to Makefile

./Makefile

MCP_MAKEFILE_LOG_LEVEL

Logging level (DEBUG, INFO, WARNING, ERROR)

INFO

MCP_MAKEFILE_ALLOWED_TARGETS

Comma-separated list of allowed targets

All non-internal targets

MCP_MAKEFILE_MAX_OUTPUT_CHARS

Maximum characters to return from target output (0 = unlimited)

0 (unlimited)

MCP_MAKEFILE_WRITE_TO_FILE

Write full output to temporary files (true/false)

false

MCP_MAKEFILE_TEMP_DIR

Base directory for temporary files

/tmp

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/tmp

Output 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 = unlimited

Via command-line argument:

mcp-makefile-server serve ./Makefile --max-output-chars 5000

When 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=true

Via command-line argument:

mcp-makefile-server serve ./Makefile --write-to-file

When enabled, you'll see:

Full output written to: /tmp/mcp-makefile-4a3f2e1b/test-1234567890.log

Customize 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/tmp

The 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 project

This 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 clean

If 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-server

Troubleshooting

Connection Failed

If Claude Code shows "Failed to reconnect to makefile-server":

  1. Check the command name is mcp-makefile-server (not mcp-makefile)

  2. Verify the Makefile path is correct

  3. Check the server logs: Look at Claude Code's output panel

  4. 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 --staging

Format Rules:

Target Type

Result

Targets with ## descriptions

Exposed as MCP tools

Targets with ## @internal or ## @skip

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"; \
	fi

Avoid:

# 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 output

Description 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 (#) for developers, but make ## comments verbose natural language instructions for the AI. Include all variables, options, and capabilities. Keep targets multi-purpose to reduce total count.

test: ## Run test suite with pytest. Options: VERBOSE=1 for detailed output, TEST=pattern to filter, COVERAGE=1 for coverage report, PARALLEL=1 for parallel execution. Creates test-results.log with full output.

Mark helper targets as internal

Sub-functions and helpers the AI doesn't need should be marked @internal or @skip to keep the tool list focused

_setup-env: ## @internal Initialize environment variables

Use variables, not multiple targets

Pass options via variables instead of creating separate targets

make test VERBOSE=1 instead of make test-verbose

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

command > output.log 2>&1 && echo "✓ Done. See output.log"

Use @ prefix

Suppress command echo to reduce output noise

@pytest instead of pytest

Use --quiet/-q flags

Use quiet flags when available

pytest --quiet, ruff check --quiet

Redirect to log files

Save verbose output for later analysis

pytest -v > test.log 2>&1

Print concise summaries

Show brief success/failure instead of full output

echo "✓ Tests passed (23 tests, 2.5s)"

Combine redirect + summary

Redirect full output to file, then echo summary message

pytest -v > test.log 2>&1 && echo "✓ Done. See test.log"

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

simple.mk

Basic targets

categorized.mk

With category organization

mixed.mk

Shows internal targets and filtering

License

MIT License

Available Tools

12 tools
checkB

Run all static checks and security scans (depends on: format, lint, type-check, security-scan)

ParametersJSON Schema
NameRequiredDescriptionDefault
variablesNoMake variables to pass (e.g., {'DEBUG': '1'})
timeoutNoTimeout in seconds (default: 300, max recommended: 3600)

TDQS

B3.3/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
variablesNoMake variables to pass (e.g., {'DEBUG': '1'})
timeoutNoTimeout in seconds (default: 300, max recommended: 3600)

TDQS

D1.9/5.0
Behavior1/5

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.

Conciseness2/5

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.

Completeness1/5

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.

Parameters3/5

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.

Purpose3/5

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.

Usage Guidelines1/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
variablesNoMake variables to pass (e.g., {'DEBUG': '1'})
timeoutNoTimeout in seconds (default: 300, max recommended: 3600)

TDQS

C2.8/5.0
Behavior2/5

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.

Conciseness3/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
variablesNoMake variables to pass (e.g., {'DEBUG': '1'})
timeoutNoTimeout in seconds (default: 300, max recommended: 3600)

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness3/5

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.

Completeness2/5

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.

Parameters2/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
variablesNoMake variables to pass (e.g., {'DEBUG': '1'})
timeoutNoTimeout in seconds (default: 300, max recommended: 3600)

TDQS

C2.8/5.0
Behavior2/5

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.

Conciseness3/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
variablesNoMake variables to pass (e.g., {'DEBUG': '1'})
timeoutNoTimeout in seconds (default: 300, max recommended: 3600)

TDQS

A3.7/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines4/5

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)

ParametersJSON Schema
NameRequiredDescriptionDefault
variablesNoMake variables to pass (e.g., {'DEBUG': '1'})
timeoutNoTimeout in seconds (default: 300, max recommended: 3600)

TDQS

B3.2/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
variablesNoMake variables to pass (e.g., {'DEBUG': '1'})
timeoutNoTimeout in seconds (default: 300, max recommended: 3600)

TDQS

B3.3/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
variablesNoMake variables to pass (e.g., {'DEBUG': '1'})
timeoutNoTimeout in seconds (default: 300, max recommended: 3600)

TDQS

C2.3/5.0
Behavior1/5

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.

Conciseness3/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose3/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
variablesNoMake variables to pass (e.g., {'DEBUG': '1'})
timeoutNoTimeout in seconds (default: 300, max recommended: 3600)

TDQS

B3.1/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
variablesNoMake variables to pass (e.g., {'DEBUG': '1'})
timeoutNoTimeout in seconds (default: 300, max recommended: 3600)

TDQS

B3.2/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
variablesNoMake variables to pass (e.g., {'DEBUG': '1'})
timeoutNoTimeout in seconds (default: 300, max recommended: 3600)

TDQS

A3.6/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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.

  1. 12 tool updatesv0.1.0
    • First observedcheck
    • First observedclean
    • First observedformat
    • First observedhelp
    • First observedlint
    • First observedrelease
    • First observedsecurity-scan
    • First observedsync
    • First observedtest
    • First observedtest-coverage
    • First observedtype-check
    • First observedversion

TDQS

B3.2/5.0

Scored across 12 tools

Disambiguation4/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityInactive
ResponsivenessNo issues

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

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    An 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
  • A
    license
    B
    quality
    C
    maintenance
    Exposes 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.
    5
    42
    3
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Exposes Just recipes as MCP tools, allowing AI assistants to discover and execute project commands defined in Justfiles.
    18
    1
    MIT