Dynamic MCP Server (Portland Ky Guy)

动态MCP服务器

用于模型上下文协议（MCP）的多功能服务器，可从JSON文件动态配置工具。

原理

这 dynamic-mcp-server 是一个单一的可执行文件，可以为多个不同的MCP服务器供电。每个服务器的行为由启动时加载的JSON配置文件定义。这意味着您可以使用不同的工具和提示创建许多不同的MCP服务器，所有这些都来自同一个运行实例。

下图说明了这种架构：

+------------------------+      +----------------------+      +-----------------+
|  Configuration File 1  |----->|                      |----->|   Model's CLI   |
| (e.g., code-review.json)|      |                      |      | (claude, gemini)|
+------------------------+      | dynamic-mcp-server   |      +-----------------+
                                | (this project)       |
+------------------------+      |                      |      +-----------------+
|  Configuration File 2  |----->|                      |----->|   Model's CLI   |
| (e.g., docs-qa.json)   |      |                      |      | (claude, gemini)|
+------------------------+      +----------------------+      +-----------------+

⚠️ 警告：危险运行模式⚠️

默认情况下，此服务器配置为在与以下对象交互时使用某些“危险”标志 claude, codex，以及 gemini CLIs（例如。， --dangerously-skip-permissions, --dangerously-bypass-approvals-and-sandbox, -y).这些标志用于开发和测试目的，在生产环境中应极其谨慎地使用，因为它们可以绕过重要的安全机制。审查 src/main.js 了解这些标志，并在您的用例需要更严格的安全性时对其进行修改。

用例

这 dynamic-mcp-server 可用于创建各种与AI模型集成的强大工具。以下是一些示例：

• 代码审查代理： 创建一个工具，用于检查代码的样式、错误和最佳实践。您可以将其配置为使用特定的模型和提示，以符合您团队的编码标准。
• 文件助理： 构建一个工具，可以回答有关代码库的问题，生成文档，或提供如何使用特定功能的示例。
• 自定义工作流： 实施涉及多个AI模型的复杂工作流程。例如，您可以创建一个工作流，首先使用代码生成模型编写函数，然后使用代码审查模型检查生成的代码。
• CLI前端： 这 dynamic-mcp-server 允许您为Gemini、Claude和Codex等模型创建CLI前端。这对于喜欢从命令行与这些模型交互但仍想利用MCP功能的用户非常有用。
• 特定型号提示： 与其依赖通用提示 dynamic-mcp-server 允许您根据每个模型的优势创建特定于模型的提示。这可以带来更好的结果和更高效的工作流程。

______________________________________________________________________

CLI版本

此项目基于以下CLI版本并使用其进行了测试：

• 克劳德代码：1.0.128
• 食品法典委员会命令行界面：0.73.0
• Gemini命令行界面：0.21.0

______________________________________________________________________

创建动态MCP服务器

创建新 dynamic-mcp-server，您需要定义一个JSON配置文件。此文件指定要使用的模型、要公开的工具以及每个工具的提示。

配置文件结构

服务器是使用JSON文件配置的。此文件可以位于文件系统上的任何位置。

{
  "name": "architect-reviewer",
  "model": "gemini",
  "modelId": "gemini-2.5-flash",
  "tools": [
    {
      "name": "ci-cd-review",
      "description": "A description of what my tool does.",
      "prompt": "A prompt template using {{variable}} syntax.",
      "inputs": [
        {
          "name": "variable",
          "type": "string",
          "description": "Description of the input.",
          "required": true
        }
      ]
    }
  ]
}

配置选项

工具定义

每个工具的日志覆盖应用于服务器级日志之上。CLI标志仍然优先于一切。 | command / args |否|可选；当前未由服务器执行。模型提示驱动CLI调用。扩展 src/main.js 如果你想要每个工具的shell命令。 |

工具论证如何成为最终提示

当调用工具时，服务器会生成一个传递给模型CLI的提示字符串：

• 如果 prompt 或 promptFile 如果提供了模板，则使用该模板 {{variable}} 占位符被传入的工具参数替换。
• 如果没有提供提示模板，服务器将回退到：

- 第一 string 输入值（如果有），否则 - JSON.stringify(toolParams) 对于所有输入。

• 如果CLI --prompt 如果使用了标志，则该前缀前面会加上换行符。

输入定义

看 examples/ 用于示例配置的文件夹。

日志记录

默认情况下，日志记录在 info 级别并写入 stderr配置优先级为：CLI标志>环境变量>配置文件>默认值。

当 format 是 json，每个日志条目包括 serverName 因此，您可以将日志与多个MCP服务器实例区分开来。

配置示例：

{
  "logging": {
    "level": "info",
    "format": "json",
    "destination": "stderr",
    "categories": ["requests", "responses", "steps"],
    "logPayloads": false,
    "payloadMaxChars": 2048
  }
}

日志字段：

环境变量：

• DYNAMIC_MCP_LOG_ENABLED
• DYNAMIC_MCP_LOG_LEVEL
• DYNAMIC_MCP_LOG_FORMAT
• DYNAMIC_MCP_LOG_DESTINATION
• DYNAMIC_MCP_LOG_CATEGORIES
• DYNAMIC_MCP_LOG_PAYLOADS_ENABLED
• DYNAMIC_MCP_LOG_PAYLOAD_MAX_CHARS

______________________________________________________________________

使用动态MCP服务器

一旦您为您的 dynamic-mcp-server，您需要配置模型的CLI才能使用它。

安装

首先，安装 dynamic-mcp-server 全球地：

npm install -g .

这使得 dynamic-mcp-server PATH上可用的命令。在MCP客户端配置（Claude、Codex、Gemini）中，将服务器命令设置为 dynamic-mcp-server 并将JSON配置路径与 --config 标志（以及任何类似的标志 --async 或 --prompt).

有关贡献和发布过程的详细信息，请参阅 CONTRIBUTING.md.

MCP客户端配置

MCP客户是您的Codex、Claude、Gemini CLIs。这些设置告诉您的CLI可用的内容以及如何使用您创建的动态mcp服务器。

CLI选项

提示前缀

这 --prompt 选项允许您在每个任务前添加系统提示。这有助于：

• 在所有工具中设置一致的行为
• 添加项目特定的上下文或指导方针
• 定义输出格式要求

备注：Prompt可以在MCP服务器配置级别使用，从而应用于该服务器中的所有工具，也可以在工具定义级别使用，为工具提供特定的提示。

使用提示文件：

dynamic-mcp-server --config /path/to/config.json --prompt /path/to/system-prompt.txt

使用文字字符串：

dynamic-mcp-server --config /path/to/config.json --prompt "Always respond in JSON format"

提示文件示例 (examples/code-review-prompt.txt):

这是一个非常简单的提示。不建议使用，因为它还没有经过审查。这里仅作为示例。

You are an expert code reviewer with deep knowledge of software engineering best practices.

When reviewing code, always consider:
- Security vulnerabilities (OWASP Top 10)
- Performance implications
- Maintainability and readability
- Error handling and edge cases
- Adherence to SOLID principles

Be constructive and specific in your feedback. Reference line numbers when applicable.

当与 code-review.json config，每个代码审查任务都会预先添加此提示。

______________________________________________________________________

验证和烟雾测试

两层检查有助于及早发现协议或CLI回归：

• 快速握手烟雾： dynamic-mcp-server --config /path/to/config.json --handshake-and-exit

- 将握手JSON打印到stdout后退出；在运行客户端之前确认接线很有用。

• 仅协议（无外部CLIs）： npm run verify:protocol

- 生成物 src/main.js --handshake-and-exit 随着 __tests__/test-config.json 并验证握手JSON。 - 如果输出包含“error”或不是JSON，则失败。

• CLI特定烟雾（每种型号）： npm run verify:clients

- 验证每个CLI(claude, codex, gemini)已安装，并且至少是“CLI版本”中列出的版本。 - 对每个型号进行仅握手烟雾测试；捕获stdout/stderr到临时文件并自动删除它们。 - 丢失/未经身份验证的CLI将被跳过，并显示一条明确的消息。

• 完整的CLI练习： npm run verify:clients:full （套 EXERCISE_CLI=1)

- 此外，使用以下命令通过每个CLI运行一个简单的工具调用 executeTask. - 断言预期的文本，检查stdout和stderr都不包含“error”，并通过陷阱清理临时文件。 - 默认情况下跳过Gemini的练习步骤，因为它的CLI可以自动调用工具并发出配额错误；集 SKIP_GEMINI_EXERCISE=0 强迫它。 - 注意：维护人员很少使用Gemini CLI，因此Gemini支持可能落后于Claude/Codex；如果你依赖双子座，就进行强制锻炼；如果双子座崩溃，就进行开放式锻炼。

• 已知限制：

- Gemini CLI可以自动调用工具并返回配额错误；默认情况下，其运动测试处于关闭状态。 - 默认的CLI标志是“危险的”，应该在生产中收紧。 - 异步作业仅在内存中；它们无法在进程重启后存活。

先决条件

• Node.js环境。
• 已安装并经过身份验证的CLIs型号： claude, codex, gemini.
• 此项目假定的CLI标志：

- 克劳德： --dangerously-skip-permissions - 食品法典： --dangerously-bypass-approvals-and-sandbox --search exec --skip-git-repo-check - 双子座： -y -p

• 如果较新的CLI版本更改了这些标志，CLI冒烟测试将很快失败，并打印检测到的版本，以便您进行更新 src/main.js / CLI_CONFIG.

文物和清理

• 通过创建临时文件 mktemp；已删除 EXIT 陷阱。
• 失败时，脚本会打印临时文件路径，以便您可以检查它们；关于成功， /tmp 保持干净。
• 集 DEBUG_KEEP=1 保留临时文件以进行调试。

______________________________________________________________________

异步模式

一些MCP客户端有工具执行超时。对于长时间运行的任务，您可以使用以下命令启用异步模式 --async 启动服务器时标记。这为所有工具设置了默认值，但每个工具都可以用以下方式覆盖行为 async: true 或 async: false 在配置中。

从异步模式开始：

dynamic-mcp-server --config /path/to/config.json --async

启用异步时（通过 --async 或工具 async: true 设置），服务器将在后台启动任务并返回 jobId 立即。使用内置 check-job-status 工具进行轮询，直到作业完成 completed 或 failedThe check-job-status 只要存在至少一个异步工具，就会注册该工具。

超时： 异步作业的上限为 DYNAMIC_MCP_JOB_TIMEOUT_MS （默认值：20分钟）。当达到超时时间时，子流程终止，作业被标记 failed.

每个工具异步覆盖示例：

{
  "name": "mixed-async-server",
  "model": "gemini",
  "tools": [
    { "name": "fast-sync", "description": "Quick task", "async": false },
    { "name": "long-async", "description": "Long-running task", "async": true }
  ]
}

克劳德

在模型的配置文件中（例如。， ~/.claude/config.json)，您可以为添加多个条目 dynamic-mcp-server，每个都有自己的配置文件。

对于具有自定义配置的动态MCP服务器：

{
  "mcpServers": {
    "architecture-reviewer": {
      "command": "dynamic-mcp-server",
      "args": ["--config", "/path/to/dynamic-mcp-server-config-for-architecture-reviewer.json", "--async"],
      "timeout": 120
    }
  }
}

使用提示前缀（字符串或文件路径）：

{
  "mcpServers": {
    "tech-manager": {
      "command":"dynamic-mcp-server",
      "args": ["--config", "/path/to/dynamic-mcp-server-config-for-tech-manager.json", "--prompt", "/path/to/system-prompt.txt", "--async"],
      "timeout": 120
    }
  }
}

这 timeout 字段（以秒为单位）控制启动超时。对于Claude-cli，默认值为60秒。工具执行有一个硬编码的10分钟限制。

现在，当您运行模型的CLI时，它将自动启动 dynamic-mcp-server 对于每个条目，并使您在配置文件中定义的工具可用。

法典

设置codex config.toml 比如：

对于动态MCP服务器：

[mcp_servers.architect-reviewer]
command = "dynamic-mcp-server"
args = ["--config", "/path/to/dynamic-mcp-server-config-for-architecture-reviewer"]
startup_timeout_sec = 60
tool_timeout_sec = 2400

使用提示前缀：

[mcp_servers.tech-manager]
command = "dynamic-mcp-server"
args = ["--config", "/path/to/dynamic-mcp-server-config-for-tech-manager.json", "--prompt", "/path/to/system-prompt.txt"]
startup_timeout_sec = 60
tool_timeout_sec = 2400

确保 tool_timeout_sec 这样动态mcp服务器就可以完成它的工作。

双子座

对于Gemini，您将在 gemini CLI的配置文件。

对于动态MCP服务器：

{
  "mcp-servers": {
    "architect-reviewer": {
      "command": "dynamic-mcp-server",
      "args": ["--config", "/path/to/dynamic-mcp-server-config-for-architecture-reviewer.json", "--async"]
    }
  }
}

使用提示前缀（字符串或文件路径）：

{
  "mcp-servers": {
    "tech-manager": {
      "command":"dynamic-mcp-server",
      "args": ["--config", "/path/to/dynamic-mcp-server-config-for-tech-manager.json", "--prompt", "/path/to/system-prompt.txt", "--async"]
    }
  }
}

现在，当你奔跑时 gemini，它将自动启动 dynamic-mcp-server 对于每个条目，并使您在配置文件中定义的工具可用。

本软件按“原样”提供，用户承担与其使用相关的所有风险和责任。存储库的所有者不对使用此软件可能产生的任何问题、困难、损失、损坏或其他责任负责。

AI使用

人工智能被用于一些编码、测试和文档。Human拥有原始想法、原始代码，并执行了所有代码审查。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。