动态CLI与MCP服务器
这个项目提供了一个可配置的命令行HTTP客户端，以及一个 模型上下文协议（MCP）服务器。这两个组件从（某个地方）加载其行为 存储在Markdown中的共享JSON配置文件和可执行脚本 文件。
项目布局
config/
cli_config.json # Main configuration file shared by CLI and MCP server
commands.md # Markdown sections describing command behaviour & scripts
src/dynamic_cli/
cli.py # Dynamic Typer-based CLI entry point
config.py # Typed configuration loader
embedding.py # SQLite-backed embedding store with OpenAI vectors
markdown_parser.py# Markdown section parser
mcp_server.py # FastAPI MCP server
scripting.py # Script execution helpers exposed to Markdown sections配置格式
config/cli_config.json 驱动着CLI（命令行界面）和MCP服务器。最 重要的要点是：
markdown_path存储命令描述的Markdown文件的路径
以及请求/响应脚本。
commands顶级命令数组。每个命令包含：
- name 并且 help 文本。 - subcommands一个子命令定义的数组。每个子命令 参考文献 a script_section 从Markdown文件中识别并定义 参数元数据以及一个基本的HTTP请求描述。
secrets名为秘密描述符。支持的类型包括env，value，
file，和 command脚本可以通过以下方式请求这些 helpers.secret(name).
mcpMCP服务器嵌入式存储的配置。请提供
embedding_model （例如。 text-embedding-3-small） persist_path 对于 SQLite 缓存，以及 api_key_env/api_base 确定如何称呼的值 OpenAI嵌入式API。
http_timeout为出站HTTP请求应用可选的全局超时设置。
参数定义
JSON模式中的参数声明了CLI参数如何映射到HTTP请求 部件：
param_type：option（默认）生成一个--flag风格选项；argument
创建一个位置参数。
location解析后的值被插入的位置path，query，header，或者
json （对于请求体）。
target可选地覆盖用于HTTP有效载荷内部的键。type控制CLI解析。支持的原语是str，int，float，
bool，以及 json （该功能将JSON字符串解析为Python字典）。
Markdown中的脚本
Markdown文件被分为多个部分，这些部分由包含三个（某种元素或符号）的行分隔开 连字符。每个部分都以YAML元数据开始（id， command，以及 subcommand)，接着是自由格式的文档说明和一个Python代码块。该 代码必须暴露两个可调用对象：
def prepare(request, helpers):
"""Mutate or replace the outbound HTTP request."""
return request
def process_response(response, helpers):
"""Post-process the API response before it is returned."""
return response这个（或“它”） helpers 脚本内的对象提供：
helpers.secret(name)从配置中解析出已命名的密钥（使用
支持环境变量、字面值、文件或shell命令。
helpers.env(name, default=None)获取环境变量，使用一个
可选默认值。
helpers.json(value)为……提供的便捷封装/包装json.dumps。
脚本可以自由地修改头部信息、查询参数、URL、请求体，甚至 完全重定向请求。任何未处理的异常都会作为命令行界面（CLI）错误显示。
CLI 使用方法
通过指向配置文件来运行CLI：
python -m dynamic_cli.cli --config config/cli_config.json storage list my-bucket --prefix images/命令行界面（CLI）根据JSON模式构建基础HTTP请求，并执行相关操作 prepare 用于富集的脚本，执行HTTP调用 httpx，然后 将回应交给 process_response 在打印前进行后处理 结果。
MCP服务器
MCP服务器提供了REST端点，供大型语言模型（或其他客户端）使用 检索命令元数据，包括增强的描述和请求模式。 使用以下命令启动它：
python -m dynamic_cli.mcp_server serve --config config/cli_config.json --host 0.0.0.0 --port 8765关键终点：
GET /commands– 列出所有带有模式元数据的命令。POST /query– 基于命令描述的语义搜索。终端点
返回排名匹配的结果，使大型语言模型（LLM）能够选择最合适的命令并 组装一个有效的请求有效载荷。
嵌入是通过OpenAI嵌入REST API生成的，并缓存在一个 本地SQLite数据库。当命令描述或模式发生变化时，仅 受影响的部分会触发一个新的API调用。设置名为 mcp.api_key_env （默认为 OPENAI_API_KEY）。 用于离线开发或 测试，定义 DYNAMIC_CLI_USE_HASH_EMBEDDINGS=1 切换到确定性（模式/方法） 基于哈希的嵌入生成器。
管理界面（或管理用户界面）
导航至 GET /ui 打开一个轻量级的HTML控制面板。它列出了 命令让你能够编辑并持久化共享的配置JSON，同时提供 一个小型的框架，用于在配置好的环境中运行命令/子命令对 脚本用于验证请求增强行为，且无需离开浏览器。
推荐的堆栈（或技术栈）
- 语言Python 3.11及以上版本
- CLI框架： Typer（可译为“打字员”或根据上下文具体含义翻译，此处保留原词以体现专业术语或特定语境） 为了符合人体工程学的操控（或指令）
定义和自动生成帮助文档。
- HTTP客户端： httpx 用于稳健的异步/同步
HTTP请求。
- Markdown 解析原生解析辅以
PyYAML用于前面/针对前面
物质处理。
- 脚本沙盒轻便的
exec基于（某种技术或框架）的加载器，配备有精心挑选的辅助工具
表面（scripting.py）。
- MCP服务器： FastAPI （介词）和；与；带着；用；凭借；具有
Uvicorn（注：Uvicorn是一个用于构建异步ASGI服务器的Python库，直接翻译为中文可能无具体含义，通常保留原名使用） 用于托管，暴露命令 通过简单的REST端点实现检索工具。
- 向量存储通过自定义SQLite支持的存储库进行填充
OpenAI嵌入式API 支持可选的确定性哈希功能，以便进行离线测试。
这些选择使得整个堆栈以Python为核心，易于部署，并且对用户友好 嵌入式/离线场景。