MCP Makefile Server

MCP制作文件服务器

\[！提示\] 使用此MCP服务器可以轻松地将Makefile目标作为MCP工具公开。让AI代理通过模型上下文协议执行Makefile目标。

目录

• mcp makefile server的价值是什么？
• 特性
• TL；DR-最简单的设置
• 使用模式

- 项目范围与全局配置

• 快速开始

- 先决条件 - 安装方法1：使用uvx（推荐） - 安装方式2：就地安装 - Claude代码设置

• 高级配置

- 允许的目标筛选器 - 默认值 - 环境变量 - 输出管理

• 删除和卸载
• 故障排除
• 生成文件格式
• 发展
• 最佳实践
• 例子
• 许可证

mcp makefile server的价值是什么？

特性

TL；DR-最简单的设置

在您的项目目录中，使用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

完成！ 您的Makefile目标为 ## 评论现在可以作为工具使用。

______________________________________________________________________

使用模式

项目范围与全局配置

推荐：项目范围

使用此MCP服务器的最佳方式是将其指向您的 当前项目的Makefile 使用 --scope project这种方法：

• 允许Claude Code访问特定于项目的目标
• 保持每个项目的自动化隔离和相关
• 允许不同的项目具有不同的Makefile目标

备选方案：全局配置

您可以使用 --scope global 使服务器在所有项目中都可用。如果您有以下情况，这将非常有用：

• 具有常见任务的共享实用程序Makefile
• 您希望在任何地方都可以使用的跨项目工具

两种配置

您可以配置 两者 全局实例和项目特定实例：

• 全局实例：指向共享实用程序Makefile(~/makefiles/common.mk)
• 项目实例：每个项目都指向自己的 ./Makefile

每个实例都可以指向不同的Makefile并公开不同的目标。全局实例提供共享工具，而项目实例提供特定于项目的自动化。

______________________________________________________________________

快速开始

先决条件

安装uv （如果你没有）：

curl -LsSf https://astral.sh/uv/install.sh | sh

这给了你们两个 uv 和 uvx 命令。

______________________________________________________________________

安装方法1：使用uvx（推荐）

不需要克隆！ uvx 直接从GitHub运行：

# Test it works - preview your Makefile targets
uvx --from git+https://github.com/ccollicutt/mcp-makefile-server mcp-makefile-server preview ./Makefile

这有什么作用：

• 从GitHub下载并缓存服务器
• 运行 preview 命令在你的 ./Makefile
• 显示将暴露哪些工具

输出示例：

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

就是这样！现在跳到 Claude代码设置 在......下面

______________________________________________________________________

安装方式2：就地安装

如果需要修改代码，请使用此选项。

步骤1：克隆并安装

git clone https://github.com/ccollicutt/mcp-makefile-server.git
cd mcp-makefile-server
uv pip install .

第二步：测试它是否有效

# 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

______________________________________________________________________

发展： 看 开发.md 获取开发设置说明。

Claude代码设置

为您的项目配置MCP服务器：

如果您使用方法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"
  ]
}'

如果使用方法2（本地安装）：

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"
  ]
}'

这有什么作用：

• 创建 .mcp.json 在项目根目录中（项目范围）
• 配置Claude代码，使其在处理此项目时将Makefile目标用作工具

对于全局设置（适用于所有项目）：

替换 --scope project 随着 --scope global 在上面的命令中。不过，这创建了一个全局MCP配置 建议使用项目范围 因为每个项目通常都有自己的Makefile，其中包含项目特定的目标。

您可以配置这两个： 共享实用程序的全局实例和每个项目Makefile的项目特定实例。

下一步： 重新启动Claude Code以加载服务器。

高级配置

允许的目标筛选器

限制可以执行的目标：

使用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"
  ]
}'

使用本地安装：

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"
  ]
}'

默认值

服务器使用合理的默认值开箱即用：

换言之： 服务器将所有输出直接返回给客户端，不进行截断或文件写入，执行任何记录的目标，并在5分钟后超时。

环境变量

服务器也可以通过环境变量进行配置：

在Claude代码中使用环境变量：

您可以在 .mcp.json 配置：

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"
  }
}'

这将服务器配置为：

• 使用DEBUG日志记录
• 截断5000个字符的输出
• 将完整输出写入文件 /var/tmp/mcp-makefile-{random-id}/

看 Claude代码设置文档 了解更多信息。

在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

输出管理

服务器提供了两种管理大输出的选项：

选项1：截断输出（可选）

默认情况下，输出为 无限。为了防止令牌过载，您可以启用截断：

通过环境变量：

export MCP_MAKEFILE_MAX_OUTPUT_CHARS=5000  # Set >0 to truncate, 0 = unlimited

通过命令行参数：

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

当输出被截断时，您将看到如下消息：

Note: Output exceeded 5000 characters and was truncated.
Configure targets to log verbose output to files and return summaries instead.

选项2：写入临时文件

将完整输出写入临时文件并返回文件路径。服务器为每个会话创建一个唯一的子目录来组织输出文件。

通过环境变量：

export MCP_MAKEFILE_WRITE_TO_FILE=true

通过命令行参数：

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

启用后，您将看到：

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

自定义临时目录位置：

# 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

服务器自动创建随机化子目录（例如。， mcp-makefile-{random-id})在temp目录中组织该会话的所有输出文件。

您可以将这两个选项组合在一起 截断返回的输出，同时在文件中保留完整副本。

______________________________________________________________________

删除和卸载

从克劳德代码中删除

要从项目中删除MCP服务器，请执行以下操作：

cd ~/projects/my-app
claude mcp remove "makefile-server" -s project

这将从中删除服务器 .mcp.json.重新启动Claude Code以应用更改。

卸载服务器

如果您使用方法1（uvx）：

服务器会自动缓存。要清除它：

# Clear specific package from cache
uv cache clean mcp-makefile-server

# Or clear entire uv cache
uv cache clean

如果使用方法2（本地安装）：

# Uninstall the package
uv pip uninstall mcp-makefile-server

# Optionally, remove the cloned directory
rm -rf /path/to/mcp-makefile-server

______________________________________________________________________

故障排除

连接失败

如果Claude代码显示“重新连接到makefile服务器失败”：

1. 检查命令名称是否 mcp-makefile-server （不是 mcp-makefile)
2. 验证Makefile路径是否正确
3. 检查服务器日志：查看Claude Code的输出面板
4. 手动测试服务器：

   uvx --from git+https://github.com/ccollicutt/mcp-makefile-server mcp-makefile-server preview ./Makefile

______________________________________________________________________

生成文件格式

您的Makefile必须使用标准的自文档格式 ## 评论：

.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

格式规则：

发展

有关开发设置、测试、Python API使用和贡献指南，请参阅 开发.md.

最佳实践

高效输出（令牌使用）

MCP响应消耗令牌和带宽。保持输出简洁：

良好做法：

# 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

避免：

# 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

最佳实践描述：

这 ## 描述已发送到MCP客户端/AI，因此请使其具有信息性：

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

提示：

例子

看 tests/fixtures/ 例如Makefiles：

许可证

MIT许可证