Nash MCP 服务器

Nash MCP (模型上下文协议 (MCP) 服务器) 能够无缝执行命令、Python 代码、网页内容获取以及可重用任务管理。

要求

• Python 3.11+
• Poetry 包管理器 (推荐)

安装

git clone https://github.com/nash-run/nash-mcp.git
cd nash-mcp
poetry install

功能

• 命令执行: 运行 shell 命令，带有错误处理
• Python 执行: 执行 Python 代码，带有错误处理
• 安全凭据: 存储和访问 API 密钥，无需将敏感数据暴露给 LLM
• 网页内容访问: 获取和解析网页内容以进行分析
• 任务存储库: 保存和组织可重用的工作流程和脚本

工具

执行模块

• execute_command: 运行 shell 命令，带有适当的错误处理和输出捕获
• list_session_files: 列出当前会话中的所有 Python 文件 (在创建新文件之前务必先使用此命令)
• get_file_content: 检索文件内容，用于审查和编辑现有代码
• edit_python_file: 使用精确的字符串模式匹配对现有 Python 文件进行有针对性的编辑 (首选方法)
• execute_python: 执行 Python 代码片段，可以完全访问已安装的软件包 (仅用于新文件)
• list_installed_packages: 获取有关可用 Python 软件包的信息

Web 交互

• fetch_webpage: 检索网页内容并将其转换为可读的文本格式

密钥管理

• nash_secrets: 安全地访问存储的 API 密钥和凭据。可以通过脚本中的环境变量访问。

任务管理

• save_nash_task: 创建带有嵌入式脚本的可重用任务
• list_nash_tasks: 查看所有可用的已保存任务
• run_nash_task: 检索并显示先前保存的任务
• execute_task_script: 运行已保存任务中的特定脚本
• view_task_details: 查看任务的完整详细信息，包括脚本代码
• delete_nash_task: 删除不再需要的任务

运行

这是用于 MCP 配置文件的命令

/path/to/this/repo/.venv/bin/mcp run /path/to/this/repo/src/nash_mcp/server.py

例如，如果您要将此 MCP 与 Claude Desktop 一起使用，则需要将 ~/Library/Application Support/Claude/claude_desktop_config.json 更改为：

{
  "mcpServers": {
    "Nash": {
      "command": "/Users/john-nash/code/nash-mcp/.venv/bin/mcp",
      "args": ["run", "/Users/john-nash/code/nash-mcp/src/nash_mcp/server.py"]
    }
  }
}

环境变量

Nash MCP 需要环境变量来指定所有数据文件路径。在根目录中创建一个 .env 文件，其中包含以下变量：

# 必需的环境变量
NASH_SECRETS_PATH=/path/to/secrets.json
NASH_TASKS_PATH=/path/to/tasks.json
NASH_LOGS_PATH=/path/to/logs/directory
NASH_SESSIONS_PATH=/path/to/sessions/directory

没有默认值 - 所有路径都必须显式配置。

会话管理

Nash MCP 服务器为每个服务器实例创建一个唯一的会话目录。此会话目录存储：

• 会话期间执行的 Python 脚本
• 已编辑脚本的备份文件
• 错误日志和异常信息

这种持久存储支持强大的工作流程：

1. 脚本以描述性名称保存，以便于参考
2. 可以查看和修改以前的脚本，而不是重写
3. 错误被捕获在配套文件中以进行调试

强制性工作流程

⚠️ 强制性预编码检查清单 - 在编写任何代码之前完成：⚠️

1. 检查可用软件包：list_installed_packages()
   - 了解您可以使用的库
   - 避免导入不可用的软件包
   
2. 检查可用密钥：nash_secrets()
   - 查看有哪些 API 密钥和凭据可用
   - 不要编写需要您没有的凭据的代码
   
3. 检查现有文件：list_session_files()
   - 查看已存在哪些代码
   - 避免重复现有功能
   
4. 审查相关文件内容：get_file_content("filename.py")
   - 了解现有的实现
   - 决定是编辑还是创建新的

文件编辑最佳实践

在使用 Nash MCP 时，请平衡效率和上下文保留：

1. 在使用 list_session_files() 创建新文件之前，始终检查现有文件
2. 优先使用 edit_python_file() 进行编辑，以进行小到中等的更改
3. 在以下情况下考虑创建新文件：
   • 与解释复杂的编辑相比，它在 token 效率方面更高
   • 您需要替换几乎整个文件
   • 该任务涉及全新的功能
   • 创建新文件将产生更清晰、更小的响应

黄金法则是在保持上下文和代码历史记录的同时最大限度地减少 token 的使用。

这种方法保留了脚本历史记录，维护了上下文，并使增量开发更加高效。编辑工作流程遵循以下模式：

1. 首先，检查可用资源 → list_installed_packages() 和 nash_secrets()
2. 列出所有现有文件 → list_session_files()
3. 检查相关文件的内容 → get_file_content("file_name.py")
4. 更改现有文件 → edit_python_file("file_name.py", old_content, new_content)
5. 运行修改后的文件 → execute_python("", "file_name.py") (空代码字符串，无需修改即可运行)
6. 仅当不存在类似文件时才创建新文件 → execute_python(new_code, "new_file.py")

要避免的常见错误

1. 当进行小幅编辑在 token 效率方面更高时，却创建新文件
2. 当创建新文件在 token 效率方面更高时，却进行复杂的编辑
3. 尝试使用未安装的软件包
4. 编写需要您没有的 API 密钥的代码
5. 重写已存在的功能
6. 没有在您的方法中考虑 token 效率

Token 效率指南

在决定是编辑还是创建新文件时，请考虑哪种方法会使用更少的 token：

• 编辑时: 更改很小到中等，位于特定部分，并且易于描述
• 创建新文件时: 更改将替换大部分文件，编辑将难以解释，或者需要一种全新的方法

始终致力于生成最小、最有效的输出，以完成任务，同时保持清晰度和上下文。

安全注意事项

• 命令和脚本以与 MCP 服务器相同的权限运行
• API 密钥和凭据存储在本地并作为环境变量加载
• 在执行之前始终审查脚本，尤其是在处理敏感数据时

开发

日志

服务器会发出所有操作和工具执行的详细的带时间戳的日志。这些日志存储在 NASH_LOGS_PATH 环境变量指定的目录中。

测试

poetry run pytest

带有覆盖率

poetry run pytest --cov=nash_mcp

许可证

MIT