Provides tools to interact with OpenAI-compatible API endpoints, enabling chat, comparisons, pipelines, and multi-model discussions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@qiaomu-llm-mcp compare deepseek and zai-glm on summarizing a news article"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
把多个 LLM Provider、API Key、模型路由和多模型讨论统一成一个本地 MCP 网关。 A local MCP gateway that turns many LLM providers, API keys, routing rules, and multi-model discussions into one tool surface.
中文 | English
适合这些场景：
你同时使用 Z.ai Coding Plan、DeepSeek、OpenAI-compatible API、Anthropic-compatible API、Claude Code CLI 等多套模型。
你不想把 API Key 写进提示词、脚本或 Codex 配置里。
你希望在 Codex / Claude / 其他 MCP 客户端里用同一组工具完成：单模型调用、多模型对比、流水线、HeavySkill 式多轮讨论。
你需要让最强的主控模型主持讨论，而不是把全部判断交给某一个 Provider。
本项目是本地优先工具：Provider 注册表保存在 ~/.config/qiaomu-llm/registry.json，密钥默认放在 macOS Keychain，MCP server 只暴露“密钥是否存在”，不会返回明文 Key。
安装后，MCP 客户端会看到这些工具：
工具 | 作用 |
| 列出本地配置的 Provider，并安全显示密钥状态 |
| 查看单个 Provider 的非敏感配置 |
| 查看本地配置或远程 |
| 不花 token，根据任务类型选择 Provider / Model |
| 调用单个 Provider |
| 用同一个问题对比多个 Provider |
| 串联多个模型步骤完成任务 |
| 多视角、多模型讨论，可由模型或 Codex 主持 |
| 把 Codex 主持后的讨论渲染成 Markdown / HTML 报告 |
| 通过 MCP 安全调用本机 Claude Code CLI |
Related MCP server: Proxima
用户问题
|
+-- qllm_route_task 选择模型
|
+-- qllm_chat / qllm_compare / qllm_pipeline
|
+-- 复杂议题: qllm_heavy_discuss
|
+-- 多模型独立给观点
+-- Codex 或指定模型主持
+-- qllm_heavy_render 输出 Markdown / HTML这套设计的核心不是“多叫几个模型凑热闹”，而是让不同模型承担不同角色：快速模型做初稿，强推理模型做审查，写作模型做表达，Codex 作为当前工作区里的主持人整合上下文和行动方案。
要求：
macOS 或 Linux
Python 3.10+
一个支持 MCP 的客户端，例如 Codex、Claude Desktop、Claude Code、Cursor 等
至少一个 LLM Provider 的 API Key
克隆项目：
git clone https://github.com/joeseesun/qiaomu-llm-mcp.git
cd qiaomu-llm-mcp如果你还没有 GitHub 版本，也可以先在本地目录安装：
cd /path/to/qiaomu-llm-mcppython3 -m venv .venv
.venv/bin/python -m pip install -U pip
.venv/bin/python -m pip install -e .确认可执行文件存在：
test -x .venv/bin/qiaomu-llm-mcp && echo "qiaomu-llm-mcp installed"
.venv/bin/python -c "import qiaomu_llm_mcp; print(qiaomu_llm_mcp.__version__)"MCP server 通常通过 stdio 被客户端启动。直接运行时它会等待 MCP 客户端消息，这是正常现象。
复制示例配置：
mkdir -p ~/.config/qiaomu-llm
cp examples/registry.example.json ~/.config/qiaomu-llm/registry.json编辑 ~/.config/qiaomu-llm/registry.json，保留你要用的 Provider，删除不用的 Provider。
示例中的 Z.ai Coding Plan 使用专用 Coding endpoint：
{
"base_url": "https://api.z.ai/api/coding/paas/v4",
"default_model": "glm-5.2"
}注意：Z.ai Coding Plan 要使用 https://api.z.ai/api/coding/paas/v4，不要误用通用 endpoint https://api.z.ai/api/paas/v4。
推荐使用 Keychain，不要把明文 Key 写入配置文件。
Z.ai：
security add-generic-password -U \
-s qiaomu-llm \
-a zai-glm \
-w "$ZAI_API_KEY"DeepSeek：
security add-generic-password -U \
-s qiaomu-llm \
-a deepseek \
-w "$DEEPSEEK_API_KEY"Anthropic-compatible Provider：
security add-generic-password -U \
-s qiaomu-llm \
-a anthropic \
-w "$ANTHROPIC_API_KEY"注册表里对应写法：
{
"secret_ref": "keychain:qiaomu-llm/zai-glm"
}也支持环境变量：
{
"secret_ref": "env:ZAI_API_KEY"
}但公开仓库、团队配置和长期使用建议优先 Keychain。
编辑 Codex 配置文件，例如 ~/.codex/config.toml：
[mcp_servers.qiaomu-llm]
command = "/absolute/path/to/qiaomu-llm-mcp/.venv/bin/qiaomu-llm-mcp"本机示例：
[mcp_servers.qiaomu-llm]
command = "/Users/joe/Documents/qiaomu-llm-mcp/.venv/bin/qiaomu-llm-mcp"重启 Codex 后，应该可以看到 qllm_* 工具。
编辑 Claude Desktop 的 MCP 配置：
{
"mcpServers": {
"qiaomu-llm": {
"command": "/absolute/path/to/qiaomu-llm-mcp/.venv/bin/qiaomu-llm-mcp"
}
}
}重启客户端后，确认工具列表里出现 qllm_list_providers。
{
"params": {
"response_format": "markdown"
}
}调用工具：qllm_list_providers
{
"params": {
"provider": "zai-glm",
"model": "glm-5.2",
"prompt": "Reply exactly: qiaomu-llm-mcp-ok",
"thinking_type": "disabled",
"max_tokens": 64
}
}调用工具：qllm_chat
{
"params": {
"prompt": "用三条原则解释如何开始一个可持续的冥想习惯。",
"task_type": "writing",
"providers": ["zai-glm", "deepseek", "aigocode-anthropic"],
"max_providers": 3,
"response_format": "markdown"
}
}调用工具：qllm_compare
{
"params": {
"input": "写一个面向普通人的冥想 App 产品方向。",
"steps": [
{
"name": "research",
"task_type": "research",
"instruction": "提出用户痛点、竞争差异和核心场景。"
},
{
"name": "prd",
"task_type": "writing",
"instruction": "把上一步整理成结构化 PRD 摘要。"
},
{
"name": "review",
"task_type": "review",
"instruction": "审查 PRD 摘要里的风险、遗漏和过度承诺。"
}
],
"response_format": "markdown"
}
}调用工具：qllm_pipeline
适合当前 Codex 已经掌握工作区、文件、用户偏好和上下文的场景。
{
"params": {
"question": "一个普通人如何开始冥想，并长期坚持？",
"mode": "deliberation",
"k": 4,
"host_mode": "codex",
"write_report": true,
"write_html": true
}
}调用工具：qllm_heavy_discuss
工具会返回：
多个模型的独立观点
host_prompt
可选的 Markdown / HTML 初始报告
把 host_prompt 交给 Codex 综合后，再调用 qllm_heavy_render 输出最终报告。
适合想让某个强模型直接完成主持总结的场景。
{
"params": {
"question": "如何设计一个隐私友好的冥想 App？",
"mode": "deliberation",
"k": 4,
"providers": ["zai-glm", "deepseek", "aigocode-anthropic"],
"host_mode": "model",
"host_provider": "aigocode-anthropic",
"rounds": 2,
"write_report": true,
"write_html": true
}
}如果本机安装了 Claude Code CLI，本项目还提供 qllm_claude_code_* 工具。
常见用途：
查看 Claude Code 能力：qllm_claude_code_capabilities
查看可用模型别名和本地最近使用模型：qllm_claude_code_models
非交互调用 Claude Code：qllm_claude_code_run
查看 Claude Code session：qllm_claude_code_sessions
示例：用 Sonnet 4.6 写一首诗。
{
"params": {
"cwd": "/Users/joe/Documents/智谱",
"prompt": "请用中文写一首 12 行现代诗，只输出诗。",
"model": "claude-sonnet-4-6",
"tools": [],
"user_facing": true,
"timeout": 300
}
}默认不会暴露 --dangerously-skip-permissions。需要文件编辑时，请显式设置 allowed_tools，并限制 cwd。
API Key 不应该写进 README、Prompt、Git 仓库或 MCP 请求参数。
推荐使用 keychain:<service>/<account>；工具只返回密钥状态，不返回明文。
Provider 错误信息会做敏感字段脱敏，但上游服务返回的文本仍应谨慎处理。
qllm_claude_code_run 是本机命令执行边界，默认只允许 Read，需要编辑或 Shell 时必须显式放开。
HeavySkill 报告可能包含你的问题、模型输出和上下文摘要。公开分享前请人工检查。
本项目不会提供云端代理服务，也不会替你保存 API Key。
确认 MCP 配置中的 command 是绝对路径：
ls -la /absolute/path/to/qiaomu-llm-mcp/.venv/bin/qiaomu-llm-mcp然后重启 MCP 客户端。
Registry not found创建注册表：
mkdir -p ~/.config/qiaomu-llm
cp examples/registry.example.json ~/.config/qiaomu-llm/registry.json或设置环境变量：
export QIAOMU_LLM_REGISTRY=/path/to/registry.jsonMissing Keychain secret检查服务名和账号是否一致：
security find-generic-password -s qiaomu-llm -a zai-glm -w如果没有，重新写入：
security add-generic-password -U -s qiaomu-llm -a zai-glm -w "$ZAI_API_KEY"检查三件事：
base_url 是否是 https://api.z.ai/api/coding/paas/v4
model 是否是你的 Coding Plan 可用模型，例如 glm-5.2
Keychain 中的 zai-glm 是否写入了正确 API Key
有些 Provider 的 /models endpoint 不可用，或账号不开放模型枚举。可以在 registry.json 里手动写 models 和 default_model。
开发者可运行：
.venv/bin/python -m compileall src
.venv/bin/python -m pip install -e .如果配置了真实 Provider，可在 MCP 客户端中运行：
{
"params": {
"provider": "zai-glm",
"model": "glm-5.2",
"prompt": "Reply exactly: ok",
"max_tokens": 16
}
}可选 aisuite adapter：当目标 Provider 覆盖足够稳定时再加入，不影响 Z.ai Coding Plan 专用 endpoint。
更完整的安装 smoke test 脚本。
Provider preset 管理命令。
报告模板主题和更多 HTML 输出样式。
更细粒度的成本、token 和超时预算策略。
发布前的 GitHub About、topics、social preview 和验证清单见 docs/github-publish-checklist.md。
Copyright (c) 向阳乔木
qiaomu.ai: https://qiaomu.ai
Blog: https://blog.qiaomu.ai
GitHub: https://github.com/joeseesun/
微信公众号：向阳乔木推荐看
MIT License. See LICENSE.
qiaomu-llm-mcp is a local MCP gateway for people who use multiple LLM providers and want one safe tool surface for routing, comparison, pipelines, and multi-model deliberation.
It keeps provider metadata in ~/.config/qiaomu-llm/registry.json and recommends storing secrets in macOS Keychain. The MCP tools expose secret status, not raw API keys.
One MCP server for many providers.
Bring your own keys; no hosted proxy.
Route tasks before spending tokens.
Compare providers on the same prompt.
Chain models into practical pipelines.
Run HeavySkill-style discussions where multiple models produce independent views and Codex or a selected model hosts the synthesis.
Optionally call local Claude Code CLI through a controlled MCP wrapper.
git clone https://github.com/joeseesun/qiaomu-llm-mcp.git
cd qiaomu-llm-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -U pip
.venv/bin/python -m pip install -e .mkdir -p ~/.config/qiaomu-llm
cp examples/registry.example.json ~/.config/qiaomu-llm/registry.jsonStore secrets in Keychain:
security add-generic-password -U -s qiaomu-llm -a zai-glm -w "$ZAI_API_KEY"For Z.ai Coding Plan, use the Coding endpoint:
https://api.z.ai/api/coding/paas/v4not the general endpoint:
https://api.z.ai/api/paas/v4[mcp_servers.qiaomu-llm]
command = "/absolute/path/to/qiaomu-llm-mcp/.venv/bin/qiaomu-llm-mcp"Restart Codex and look for qllm_* tools.
qllm_list_providers: list configured providers and secret status.
qllm_chat: call one provider.
qllm_compare: compare several providers.
qllm_pipeline: run sequential model steps.
qllm_heavy_discuss: run multi-model deliberation.
qllm_heavy_render: render Codex-hosted synthesis to Markdown / HTML.
qllm_claude_code_run: run a bounded non-interactive Claude Code task.
Do not commit API keys.
Prefer Keychain refs such as keychain:qiaomu-llm/zai-glm.
Review generated HeavySkill reports before sharing them publicly.
Grant Claude Code file-editing or shell permissions only when the task needs them.
.venv/bin/python -m compileall src
.venv/bin/python -m pip install -e .Then call qllm_list_providers from your MCP client.
Created and maintained by 向阳乔木.
MIT License. See LICENSE.
Call a provider from the local qiaomu-llm registry.
Args: params (ChatInput): Provider/model selection or auto routing, prompt/messages, sampling settings, optional provider-specific thinking/reasoning fields, timeout, output size, and response format.
Returns: str: JSON or Markdown model response with provider/model/usage metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds no further behavioral context (e.g., side effects, rate limits, auth requirements), leaving the agent to infer behavior solely from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose, then a brief Args/Returns structure. Every part earns its place, with zero waste and clear front-loading.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex (many parameters, nested ChatInput), but the schema fully documents inputs and the description notes the return format. Missing details about routing or task_type behavior are covered by schema. The combination is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides detailed descriptions for all parameters, so the description's high-level categorization of parameter groups adds convenient clarification. With full schema coverage, the description offers useful summarization without being redundant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it calls a provider from the local registry for chat, using specific verb and resource. However, it does not explicitly differentiate from sibling tools like qllm_pipeline or qllm_claude_code_run, so a slight deduction applies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as qllm_pipeline or qllm_compare. The description only explains what it does, not when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect local Claude Code CLI version, wrapper capabilities, and optional help text.
Args: params (ClaudeCodeCapabilitiesInput): Optional executable path, help inclusion, timeout, and response format.
Returns: str: JSON or Markdown describing available Claude Code integration features.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safe read operation. The description adds value by specifying exactly what is inspected (version, wrapper capabilities, help text) and the return format (JSON or Markdown), providing behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence for purpose, followed by structured Args and Returns sections. It is front-loaded and contains no superfluous text, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description conveys the basic operation and return type (string), but lacks details about the returned JSON structure or keys, especially since there is no output schema provided. It is adequate but could be more exhaustive given the complexity of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description summarizes the parameter group ('Optional executable path, help inclusion, timeout, and response format') but does not add meaning beyond the input schema, which already contains detailed descriptions for each property. Because schema description coverage is effectively high (per the schema), the description offers marginal added value, achieving the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Inspect' and the resource 'local Claude Code CLI version, wrapper capabilities, and optional help text'. This distinguishes it from sibling tools like qllm_claude_code_run (execution) and qllm_claude_code_models (listing models), making the tool's purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used for inspecting capabilities but does not explicitly state when to use it over alternatives, nor does it provide exclusions or prerequisites. Usage context is only implied, not actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Claude Code model aliases, docs-derived model ids, and recent local usage.
Args: params (ClaudeCodeModelsInput): Catalog/session inclusion options.
Returns: str: JSON or Markdown model information. Exact account availability can vary.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds that it returns JSON or Markdown and notes that exact account availability can vary, providing useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and follows a clear docstring structure with Args and Returns sections. It is front-loaded with the main purpose. Minor room for improvement in explaining parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one complex parameter and an output schema, the description provides enough context for an agent to understand the tool's purpose and return format. It notes variability in account availability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'Catalog/session inclusion options' which adds some context, but schema description coverage is 0% and property descriptions in the schema are detailed. The description does not fully compensate for the lack of top-level param description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists Claude Code model aliases, docs-derived model ids, and recent local usage. This distinguishes it from sibling tools like qllm_list_models which list all models.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for Claude Code-specific model info but does not explicitly state when to use this tool over alternatives or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a controlled non-interactive Claude Code CLI task.
Args: params (ClaudeCodeRunInput): Prompt, cwd, model/effort, permission mode, tool allowlists, output format, budget, timeout, and output limits.
Returns: str: JSON or Markdown with stdout/stderr and metadata. Prompt is passed via stdin.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only, non-destructive, non-idempotent, and open world. The description adds 'non-interactive' and details about stdin, stdout/stderr, but does not elaborate on potential side effects despite openWorldHint being true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences with a parameter list. It is front-loaded and every sentence serves a purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (many parameters, output schema, annotations), the description covers the essential purpose, input, and output. It does not detail every parameter but the schema compensates. Suitable for a tool with rich structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description groups parameters (Prompt, cwd, model/effort, etc.) and notes that prompt is passed via stdin, adding context beyond the schema. However, the schema already contains descriptions for most parameters, so the added value is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a non-interactive Claude Code CLI task, distinguishing it from sibling tools like qllm_chat or qllm_claude_code_sessions. The verb 'run' and resource 'Claude Code CLI' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for non-interactive code tasks but does not explicitly discuss when to use this tool versus alternatives like qllm_chat or qllm_heavy_discuss. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect recent local Claude Code JSONL sessions for models and prompts.
Args: params (ClaudeCodeSessionsInput): Cwd, limit, prompt inclusion, and output format.
Returns: str: JSON or Markdown session metadata. Raw secrets are not read from settings.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds valuable context: 'Raw secrets are not read from settings,' which goes beyond the annotations and clarifies security behavior. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus an Args/Returns block. It is front-loaded with the purpose and efficient, with no extraneous information. The Args/Returns block is slightly redundant given the schema but does not detract.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter with clear sub-properties, annotations, and an output schema, the description covers the essential use case and mentions security ('Raw secrets are not read from settings'). It does not explain session structure, but that is reasonable domain context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists parameters briefly: 'Cwd, limit, prompt inclusion, and output format.' However, the input schema already provides detailed descriptions for each sub-property (e.g., cwd's description, limit's min/max). The description adds little meaningful context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inspects recent local Claude Code JSONL sessions for models and prompts. This is a specific verb+resource that distinguishes it from siblings like qllm_claude_code_run (execution) and qllm_list_models (listing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to inspect sessions) but does not explicitly contrast with siblings or provide when-not or alternative tool references. The sibling list is provided externally but not leveraged in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call multiple providers with the same prompt and return comparable results.
Args: params (CompareInput): Same fields as qllm_chat plus providers/max_providers.
Returns: str: JSON or Markdown results from each provider. Failures are returned per provider.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that failures are returned per provider and output format (JSON or Markdown), adding value beyond annotations which only set openWorldHint. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences for purpose and a clear Args/Returns structure. No unnecessary words, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key aspects: multiple providers, same prompt, per-provider failures, and return format. Could add default behavior (e.g., 'defaults to router top providers') but overall adequate given complex input schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds comparative context ('Same fields as qllm_chat plus providers/max_providers'), but the schema already provides detailed descriptions for all CompareInput fields, so the description adds limited new meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Call multiple providers') and resource ('same prompt') with clear result ('return comparable results'). It distinguishes from siblings like qllm_chat by emphasizing multi-provider comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
References qllm_chat as a baseline ('Same fields as qllm_chat plus providers/max_providers'), implying use for comparing providers instead of single provider calls. However, no explicit when-not-to-use or alternative scenarios are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a HeavySkill-style multi-perspective discussion across providers.
Args: params (HeavyDiscussInput): Question, mode, K, optional providers/perspectives, host mode/provider/model, generation settings, and optional report writing.
Returns: str: JSON or Markdown with independent traces, host synthesis, and report paths.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-destructive, non-read-only, open world. Description adds that the tool may write reports and HTML files (if write_report set), and that host_mode can return a prompt instead of running (codex mode). These are important behavioral details beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that covers purpose, args, and returns. It is concise and front-loaded with the main action. Could be slightly more structured but not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity with many parameters and nested schema, the description adequately explains the overall concept and returns. It mentions key options like host mode and report writing. The output schema exists to detail return values. Minor gap: does not explain the two host modes in detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema (HeavyDiscussInput) contains detailed descriptions for all parameters. The description provides a high-level summary but adds little new meaning beyond what the schema already offers. The summary is useful but not essential.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a HeavySkill-style multi-perspective discussion across providers. It specifies the action (run), method (multi-perspective discussion), and scope (across providers). This distinguishes it from siblings like qllm_chat or qllm_compare.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. Usage is implied by the complexity of the discussion, but no direct guidance on when not to use or conditions for choosing over siblings like qllm_pipeline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a Codex-hosted HeavySkill synthesis to Markdown and HTML.
Args: params (HeavyRenderInput): Question, mode, collected traces, Codex synthesis, host label, and report output options.
Returns: str: JSON or Markdown with generated report paths.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate not read-only, not destructive, not idempotent. Description adds context about writing to disk (report_base_dir defaults to ~/Downloads/heavyskill-reports), which is useful beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: one for purpose, one for args and returns. Concise but the args line is a bit dense; could be split for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having a complex input schema with nested objects, the description is thin. It does not explain error handling, file output behavior, or the relationship between traces and synthesis. Output schema exists but description doesn't clarify return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Description provides a high-level summary of the params (Question, mode, traces, synthesis, etc.) but lacks detailed semantics for each field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool renders a Codex-hosted HeavySkill synthesis to Markdown and HTML. The verb 'render' and resource are specific, and the tool is distinct from siblings like qllm_heavy_discuss or qllm_chat.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description does not mention prerequisites, when-not to use, or comparison with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List configured or remote models for one provider.
Args: params (ListModelsInput): Provider id, source mode, timeout, and output format.
Returns: str: JSON or Markdown model list. Remote mode calls the provider's /models endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true. The description adds valuable context: that remote mode calls the provider's /models endpoint, and output can be JSON or Markdown. This exceeds minimal expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a single-line summary followed by an Args block. Every sentence adds value with no redundancy or clutter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (one nested parameter) and the presence of output schema and annotations, the description covers key behaviors (source modes, endpoint call) but could mention how 'auto' source resolves.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description restates parameter names (provider id, source mode, timeout, output format) without adding semantics beyond what the schema already provides. Schema coverage per context is 0%, but schema embedded descriptions actually exist, making this a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List configured or remote models for one provider,' specifying the verb (list), resource (models), and scope (per provider). This distinguishes it from siblings like qllm_list_providers and qllm_show_provider.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing models but provides no explicit guidance on when to choose this tool over alternatives, nor any conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List local qiaomu-llm providers without exposing API keys.
Args: params (ListProvidersInput): Filtering options: - include_disabled: include disabled providers - require_secret: only show providers with an available secret - capability: optional capability filter such as chat, models, tools, images - response_format: json or markdown
Returns: str: JSON or Markdown provider list with secret status only.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe operation. The description adds valuable context: 'without exposing API keys' and 'with secret status only,' which is critical for security and beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear first sentence and a structured list of arguments and returns. Every part is relevant, and there is no superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (listing providers with filters), annotations cover safety, and output schema exists, the description is sufficiently complete. It explains the return format and security aspect, though it could briefly mention the 'local' scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists the parameters and their meanings, but the input schema already contains descriptions for each property. The enum for response_format is clear from the schema. The description adds value by summarizing, but does not introduce new information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List local qiaomu-llm providers without exposing API keys.' It specifies the resource and the important security caveat, though it does not explicitly differentiate from sibling tools like qllm_show_provider.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or specific scenarios. The agent is left without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a sequential multi-model pipeline.
Args: params (PipelineInput): Initial input and 1-8 steps. Each step can set provider/model/task_type/instruction. The previous step output is passed into the next step.
Returns: str: JSON or Markdown pipeline trace and final output.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and openWorldHint=true, implying external API calls and potential side effects. The description mentions it runs a pipeline and returns a trace, but does not disclose costs, latency, or resource consumption. The timeout parameter in schema is noted but not in description. With annotations carrying part of the burden, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two short paragraphs, front-loading the main purpose. Every sentence provides relevant information without redundancy. The structure is clean and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, parameters, and return format. Given the complexity of a multi-step pipeline and the presence of annotations and output schema, the description is reasonably complete. It lacks details on error handling or execution guarantees, but these are not critical for a tool definition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description summarizes the PipelineInput as 'Initial input and 1-8 steps' and explains step autonomy and chaining. Although the input schema has individual descriptions, the description adds high-level context and structure. Given schema coverage 0% in description, it does add meaning, but the schema is rich so baseline is 3, and the extra chaining detail justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Run a sequential multi-model pipeline', which specifies the verb, resource, and structure. It distinguishes from sibling tools like qllm_chat (single interaction) and qllm_route_task (task routing) by emphasizing the multi-step sequential nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit when-to-use or when-not-to-use guidance. It implies usage for multi-model pipelines, but does not compare to alternatives or state prerequisites. The context of siblings suggests differentiation, but the description itself lacks such guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank providers for a task without calling a model.
Args: params (RouteTaskInput): Prompt/task summary, task type, candidates, and secret requirement.
Returns: str: JSON or Markdown ranking with selected provider and model.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds 'without calling a model' and return type, consistent with annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with one sentence plus structured Args/Returns. No fluff, but could front-load purpose more efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complex input schema and presence of output schema, description adequately covers purpose, input high-level, and return type. Schema fills remaining details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% from description, but the schema itself provides full descriptions for all parameters. Description only gives a high-level summary, adding little beyond schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool ranks providers for a task without calling a model, using specific verb and resource. It distinguishes from siblings like qllm_chat which actually calls a model.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for ranking providers without making a call, but does not explicitly state when to use this versus alternatives like qllm_chat or qllm_list_models. No when-not or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show one provider's non-secret metadata and secret status.
Args: params (ShowProviderInput): Provider id and output format.
Returns: str: JSON or Markdown provider metadata. Raw secrets are never returned.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent, and the description adds critical safety context: 'Raw secrets are never returned'. This goes beyond annotations and builds trust.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (four lines), front-loads the key purpose, and uses a clear Args/Returns structure without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with strong annotations, the description adds the essential safety note and clarifies the return type. It could be slightly more detailed about metadata structure, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description merely restates the parameter names and types ('Provider id and output format') with no new meaning beyond the schema's descriptions, which already cover the parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Show one provider's non-secret metadata and secret status', using a specific verb and resource, and differentiates from siblings like qllm_list_providers which likely lists all providers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for accessing details of a specific provider, and the name contrasts with listing tools, but it does not explicitly state when not to use or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0qllm_chatqllm_claude_code_capabilitiesqllm_claude_code_modelsqllm_claude_code_runqllm_claude_code_sessionsqllm_compareqllm_heavy_discussqllm_heavy_renderqllm_list_modelsqllm_list_providersqllm_pipelineqllm_route_taskqllm_show_providerScored across 13 tools
Each tool has a clear, distinct purpose. For example, qllm_chat handles single provider calls, qllm_compare compares multiple providers, and qllm_heavy_discuss facilitates multi-perspective discussions. The Claude Code tools are specialized and separate from the general chat and management tools.
All tools follow a consistent 'qllm_' prefix and snake_case naming convention. They use a verb_noun pattern (e.g., list_models, show_provider, claude_code_run) that makes their function predictable and easy to parse.
With 13 tools, the set is well-scoped. It covers chat, comparison, heavy discussion, pipelines, routing, provider management, and Claude Code integration without being excessive or sparse. Each tool addresses a specific need within the domain.
The tool set comprehensively covers the core operations of a local LLM registry: listing providers and models, calling models in various configurations (single, compare, heavy discuss, pipeline), routing, and Claude Code integration. No obvious gaps are present for the stated purpose.
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
Connect MCP clients to 2,000+ AI models without managing provider API keys.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
