mcp-this

一个通过YAML配置文件动态暴露CLI/bash命令作为工具和提示模板的MCP服务器。

mcp-this允许您将任何命令行工具转换为MCP工具，并创建结构化的提示模板，这些模板可以被任何MCP客户端（如Claude Desktop）使用。无需编写代码，只需在YAML文件中定义命令、提示及其参数，MCP服务器就会使它们对MCP客户端可用。

核心价值： 将CLI命令转换为MCP工具，并使用简单的YAML配置创建可重用的提示模板。

---

工作原理

在YAML中定义工具（CLI命令）和提示（AI模板）：

tools:
  get-current-time:
    description: |
      以各种格式显示当前日期和时间。
      
      示例：
      - get_current_time(format="iso") → 2025-05-18T17:17:39Z
      - get_current_time(format="readable") → 2025年5月18日星期五 下午5:17
    execution:
      command: >-
        if [ "<<format>>" = "iso" ]; then 
          date -u +"%Y-%m-%dT%H:%M:%SZ"; 
        elif [ "<<format>>" = "readable" ]; then 
          date "+%A, %B %d, %Y %I:%M %p"; 
        else 
          echo "ISO: $(date -u +"%Y-%m-%dT%H:%M:%SZ")"; 
          echo "Readable: $(date "+%A, %B %d, %Y %I:%M %p")"; 
        fi
    parameters:
      format:
        description: "时间格式：iso、readable或为空表示两者都使用"
        required: false

  system-info:
    description: 获取基本系统信息
    execution:
      command: uname -a && echo "CPU: $(nproc) 核心"
    parameters: {}

prompts:
  code-reviewer:
    description: 执行全面的代码审查并关注最佳实践
    template: |
      请审查以下代码，重点关注：
      - 代码质量和最佳实践
      - 安全漏洞
      - 性能考虑
      {{#if focus_area}}- 特别注意：{{focus_area}}{{/if}}
      
      待审查的代码：
      {{code}}
      
      {{#if context}}附加上下文：{{context}}{{/if}}
    arguments:
      code:
        description: 待审查的代码
        required: true
      focus_area:
        description: 需要特别关注的具体领域（例如，安全、性能）
        required: false
      context:
        description: 关于代码的附加上下文
        required: false

在Claude Desktop中使用：

{
  "mcpServers": {
    "mcp-this-custom": {
      "command": "uvx",
      "args": ["mcp-this", "--config-path", "/path/to/your-tools.yaml"]
    }
  }
}

就这样！Claude现在可以：

• 执行自定义CLI工具（get-current-time, system-info）
• 使用结构化的提示模板（带有引导参数的code-reviewer）

---

快速开始

1. 安装uvx

# 安装uv（包括uvx）
curl -LsSf https://astral.sh/uv/install.sh | sh

2. 创建您的第一个工具

创建 my-tools.yaml：

tools:
  web-scraper:
    description: 抓取网页并将其转换为干净、易读的文本
    execution:
      command: curl -s '<<url>>' | lynx -dump -stdin
    parameters:
      url:
        description: 要抓取的网页的URL
        required: true

  find-large-files:
    description: 在目录中查找大于指定大小的文件
    execution:
      command: find '<<directory>>' -type f -size +<<size>> -exec ls -lh {} \;
    parameters:
      directory:
        description: 要搜索的目录
        required: true
      size:
        description: 最小文件大小（例如，100M, 1G）
        required: true

2.1. 添加AI提示模板（可选）

增强您的 my-tools.yaml，添加结构化的提示模板：

tools:
  # ... 您的工具在此处 ...

prompts:
  summarize-webpage:
    description: 生成网页内容的结构化摘要
    template: |
      请分析以下网页内容并提供：
      
      1. **主要主题**：这个页面是关于什么的？
      2. **关键要点**：{{num_points}}个最重要的要点
      3. **目标受众**：这个内容是面向谁的？
      {{#if focus}}4. **{{focus}} 分析**：关于{{focus}}的具体见解{{/if}}
      
      内容：
      {{content}}
    arguments:
      content:
        description: 要总结的网页内容
        required: true
      num_points:
        description: 要提取的关键要点数量（默认5）
        required: false
      focus:
        description: 需要特别关注的具体方面（例如，技术、业务、教育）
        required: false

  file-analysis:
    description: 为特定目的分析文件
    template: |
      对以下文件进行{{analysis_type}}分析：
      
      {{#if criteria}}重点：{{criteria}}{{/if}}
      
      {{files}}
      
      请提供：
      - 发现的总结
      - 建议
      - {{#if format}}以{{format}}格式输出{{/if}}
    arguments:
      files:
        description: 要分析的文件内容或路径
        required: true
      analysis_type:
        description: 分析类型（安全、性能、质量等）
        required: true
      criteria:
        description: 具体的标准或规范
        required: false
      format:
        description: 输出格式（markdown、JSON、报告等）
        required: false

在Claude Desktop中使用提示：

1. 点击消息输入框中的 + 图标
2. 选择“从mcp-this-custom添加”
3. 选择您的提示（例如，“summarize-webpage”）
4. 填写参数 - Claude会引导您完成所需和可选字段

3. 配置Claude Desktop

添加到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "my-tools": {
      "command": "uvx",
      "args": ["mcp-this", "--config-path", "/path/to/my-tools.yaml"]
    }
  }
}

4. 重启Claude Desktop

您的工具和提示现在可用！Claude可以：

• 抓取网页内容并查找大文件 使用您的自定义CLI工具
• 使用结构化的提示模板 进行引导分析和总结

---

配置格式

工具定义

tools:
  tool-name:
    description: "带使用示例的描述"
    execution:
      command: "命令模板 <<parameter1>> <<optional_param>>"
    parameters:
      parameter1:
        description: "参数描述"
        required: true
      optional_param:
        description: "可选参数描述"  
        required: false

关键点：

• 在命令中使用 <<parameter>> 占位符
• 标记为 required: false 的参数如果未提供则从命令中移除
• 使用 command: >- 处理多行命令（而不是 command: |）

提示定义

prompts:
  prompt-name:
    description: "提示描述"
    template: |
      包含 {{argument}} 占位符的模板。
      {{#if optional_arg}}条件：{{optional_arg}}{{/if}}
    arguments:
      argument:
        description: "参数描述"
        required: true
      optional_arg:
        description: "可选参数"
        required: false

提示与工具的区别：

• 工具 执行命令并使用 <<parameter>> 语法
• 提示 生成文本模板并使用 {{argument}} 语法和Handlebars

---

配置方法

方法	使用	示例
YAML 文件	--config-path <path>	--config-path ./my-tools.yaml
JSON 字符串	--config-value <json>	--config-value '{"tools":{...}}'
环境变量	MCP_THIS_CONFIG_PATH	export MCP_THIS_CONFIG_PATH=./tools.yaml
内置预设	--preset <n>	--preset default

预建工具及提示集合（预设）

为了方便，mcp-this 包括了可以直接使用的工具和提示集合：

• default - 安全的只读工具（文件浏览、网页抓取）
• editing - 文件操作工具（创建、编辑、删除）
• github - GitHub集成工具（PR分析、仓库操作）+ 专用提示（代码审查、创建PR描述）

快速使用：

{
  "mcpServers": {
    "mcp-this": {
      "command": "uvx", 
      "args": ["mcp-this", "--preset", "default"]
    }
  }
}

参见 README_PRESETS.md 了解完整的预设文档、工具列表、依赖项和高级设置。

---

实际应用示例

开发工作流工具

tools:
  git-status-summary:
    description: 获取git仓库状态的简洁概述
    execution:
      command: >-
        echo "=== 分支 ===" && git branch --show-current &&
        echo "=== 状态 ===" && git status --porcelain &&
        echo "=== 最近提交 ===" && git log --oneline -5
    parameters: {}

  test-runner:
    description: 运行测试，可选模式匹配
    execution:
      command: >-
        if [ -n "<<pattern>>" ]; then
          npm test -- --grep "<<pattern>>"
        else
          npm test
        fi
    parameters:
      pattern:
        description: 测试模式匹配（可选）
        required: false

  docker-container-logs:
    description: 获取Docker容器的日志
    execution:
      command: docker logs <<container_name>> --tail <<lines>>
    parameters:
      container_name:
        description: Docker容器的名称或ID
        required: true
      lines:
        description: 显示的日志行数（默认100）
        required: false
        default: "100"

AI驱动的工作流提示

prompts:
  refactor-code:
    description: 引导代码重构，具有特定目标和约束
    template: |
      请根据以下目标重构以下代码：
      {{#if goals}}
      **目标：**
      {{goals}}
      {{/if}}
      
      **约束：**
      - 维持现有功能
      - {{#if language}}遵循{{language}}的最佳实践{{/if}}
      - {{#if performance}}优化{{performance}}{{/if}}
      {{#if additional_constraints}}
      - {{additional_constraints}}
      {{/if}}
      
      **待重构的代码：**
      ```
      {{code}}
      ```
      
      请提供：
      1. 重构后的代码及其解释
      2. 修改的总结
      3. 潜在风险或注意事项
    arguments:
      code:
        description: 待重构的代码
        required: true
      goals:
        description: 具体的重构目标（例如，提高可读性、减少复杂度）
        required: false
      language:
        description: 编程语言的最佳实践
        required: false
      performance:
        description: 性能优化目标（速度、内存等）
        required: false
      additional_constraints:
        description: 任何其他约束或需求
        required: false

  technical-documentation:
    description: 生成全面的技术文档
    template: |
      创建{{doc_type}}文档：
      
      {{content}}
      
      **要求：**
      - 目标受众：{{audience}}
      {{#if style}}- 文档风格：{{style}}{{/if}}
      {{#if sections}}- 包含部分：{{sections}}{{/if}}
      - {{#if detail_level}}详细程度：{{detail_level}}{{/if}}
      
      {{#if examples}}**包含示例：** {{examples}}{{/if}}
      
      请以清晰的标题、示例和可操作的信息结构化文档。
    arguments:
      content:
        description: 要记录的代码、API或系统
        required: true
      doc_type:
        description: 文档类型（API、用户指南、技术规格等）
        required: true
      audience:
        description: 目标受众（开发者、最终用户、管理员等）
        required: true
      style:
        description: 文档风格（正式、对话式、教程、参考）
        required: false
      sections:
        description: 需要包含的具体部分
        required: false
      detail_level:
        description: 详细程度（高层次、详细、全面）
        required: false
      examples:
        description: 需要包含的示例类型
        required: false

系统管理工具

tools:
  port-checker:
    description: 检查特定端口正在使用的进程
    execution:
      command: lsof -i :<<port>>
    parameters:
      port:
        description: 要检查的端口号
        required: true

  service-status:
    description: 检查系统服务的状态
    execution:
      command: systemctl status <<service_name>>
    parameters:
      service_name:
        description: 要检查的服务名称
        required: true

  disk-usage-analyzer:
    description: 分析磁盘使用情况并找到最大的目录
    execution:
      command: >-
        echo "=== 磁盘使用概要 ===" &&
        df -h <<path>> &&
        echo "=== 最大的目录 ===" &&
        du -h <<path>> | sort -hr | head -10
    parameters:
      path:
        description: 要分析的路径（默认当前目录）
        required: false
        default: "."

---

Python API 使用

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# 使用自定义配置
server_params = StdioServerParameters(
    command='uvx',
    args=['mcp-this', '--config-path', '/path/to/tools.yaml'],
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        
        # 列出可用工具
        tools = await session.list_tools()
        print([tool.name for tool in tools.tools])
        
        # 使用工具
        result = await session.call_tool(
            'git-status-summary',
            {}
        )
        print(result.content[0].text)

---

安装选项

通过uvx（推荐）

# 不需要安装 - uvx在隔离环境中运行工具
uvx mcp-this --config-path ./my-tools.yaml

通过pip

pip install mcp-this
mcp-this --config-path ./my-tools.yaml

从源码

git clone https://github.com/your-username/mcp-this.git
cd mcp-this
uv sync
python -m mcp_this --config-path ./my-tools.yaml

---

安全注意事项

⚠️ 重要： mcp-this 根据您的配置执行shell命令。始终：

• 仅使用可信的配置文件
• 在生产环境中验证用户输入
• 以最低必要的权限运行
• 考虑容器化以增加安全性
• 审查命令以防止危险操作

参见 安全章节 以获取详细的安全部署指导。

---

开发

设置

git clone https://github.com/your-username/mcp-this.git
cd mcp-this
uv sync

测试

make tests         # 运行所有测试
make unittests     # 仅单元测试
make linting       # 仅代码检查
make open_coverage # 查看覆盖率报告

构建

make package-build    # 构建包
make package-publish  # 发布（需要UV_PUBLISH_TOKEN）

---

许可证

Apache License 2.0