使用说明

最上层的mcp

用于搜索本地Topdrawer手册文本文件和通过外部渲染现有Topdrawer输入文件 td 可执行。

服务器公开MCP工具、资源和手动搜索提示，命令查找、脚本检查和渲染工作流。

工具：

search_manual 用于使用行号片段进行不区分大小写的子字符串搜索
reverse_lookup_commands 用于从简短的自然语言查询中发现排名命令名
lookup_command 通过规范名称或唯一别名进行结构化指挥指导
get_server_runtime_info 用于解析手动/渲染运行时配置
scan_topdrawer_script 用于从内联脚本文本中提取识别的命令
scan_topdrawer_file 用于从现有命令中提取已识别的命令 .top 文件
generate_topdrawer_png 用于从现有文件或内联脚本生成PNG输出
generate_topdrawer_postscript 用于从现有文件或内联脚本生成PostScript输出
render_topdrawer_file 用于将现有Topdrawer输入文件渲染为PNG
render_topdrawer_script 用于将内联Topdrawer脚本文本渲染为PNG
list_manual_samples 用于列出带有可选过滤器的精选示例元数据
get_manual_sample 用于按id获取一个精选的样本元数据条目

资源：

resource://commands/index 用于查看命令发现元数据
resource://commands/{command} 对于一个经过审查的顶级规范命令条目
resource://commands/{parent}/{command} 对于一个已审阅的嵌套规范命令项
动态的 resource://artifacts/{artifact_id} 生成工具返回的清单
动态的 resource://artifacts/{artifact_id}/output, /source，以及 /metadata 保留工件的子资源

提示：

inspect_topdrawer_script 用于查看现有脚本 scan_topdrawer_*, lookup_command，以及 search_manual
discover_topdrawer_command 首先通过反向查找从短语或用户意图中找到最可能的命令

范围

此存储库负责：

阅读本地纯文本Topdrawer手册
通过MCP stdio服务器公开简单的手动搜索
执行已安装的 td 二进制来呈现现有的输入文件
通过同一渲染管道执行内联Topdrawer脚本文本

此存储库不负责：

构建或包装 td 可执行文件本身
维护上游Topdrawer源代码树
重写用户提供的 .top 文件到位
超出当前商定的源策略范围的广泛手动预处理

数据

默认情况下，服务器读取：

data/topdrawer.txt

该文件被视为纯UTF-8文本。服务器不解析Topdrawer 命令、部分、生成的HTML或源代码清单。

您可以使用以下命令覆盖手动路径：

TOPDRAWER_MANUAL_PATH=/path/to/manual.txt

看 docs/source-policy.md 了解此存储库的方式处理规范的手动源、伴随源和未来生成的数据。

预处理

对于小型确定性索引，存在一个可选的构建时预处理CLI 生成任务。当前第一遍提取顶级第15章命令部分从 topdrawer.doc.

从存储库根目录运行它：

uv run topdrawer-mcp-preprocess

您可以使用以下命令覆盖源文件路径：

TOPDRAWER_DOC_SOURCE_PATH=/path/to/topdrawer.doc uv run topdrawer-mcp-preprocess

跑

从存储库根目录：

uv run topdrawer-mcp

在存储库根目录之外，使用绝对存储库路径：

uv --directory /absolute/path/to/topdrawer-mcp run topdrawer-mcp

MCP客户端配置

对于VS Code中的GitHub Copilot，全局MCP配置可以指向此通过在用户级别使用存储库的绝对路径 mcp.json，为例子：

{
  "servers": {
    "topdrawer-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/topdrawer-mcp",
        "run",
        "topdrawer-mcp"
      ],
      "env": {
        "TOPDRAWER_MANUAL_PATH": "/absolute/path/to/topdrawer-mcp/data/topdrawer.txt",
        "TD_EXECUTABLE_PATH": "/absolute/path/to/td",
        "GS_EXECUTABLE_PATH": "/absolute/path/to/gs"
      }
    }
  }
}

替换 /absolute/path/to/topdrawer-mcp 使用此的本地克隆存储库。保持 env 仅当需要覆盖手动路径时才阻止或者明确地执行解析。

该存储库还包括一个工作区本地VS代码示例：

.vscode/mcp.json

该文件使用 ${workspaceFolder}，这便于本地存储库在VS Code中使用，但不是全局IDE配置的正确模式。

渲染先决条件

使用 generate_topdrawer_png 以及兼容性渲染工具，安装顶部抽屉(td)Ghostscript(gs)所以两者都可以在 PATH.

您还可以显式覆盖已解析的可执行文件：

TD_EXECUTABLE_PATH=/path/to/td GS_EXECUTABLE_PATH=/path/to/gs uv run topdrawer-mcp

当运行MCP客户端时，传递 TOPDRAWER_MANUAL_PATH, TD_EXECUTABLE_PATH，并且可选 GS_EXECUTABLE_PATH 通过客户的环境配置，而不是编辑存储库默认值。

第一步故障排除

如果渲染相关工具失败，请调用 get_server_runtime_info 第一。

这是最快的检查方式：

手动路径是否按预期解析
是否 td 可用的
是否 gs 可用的
客户端环境覆盖是否实际到达MCP服务器

如果 td 或 gs 缺少，建议修复MCP客户端配置或调试之前显式重写可执行路径 .top 脚本本身。

MCP工具

`search_manual`

输入：

{
  "query": "BARGRAPH",
  "limit": 5,
  "context_lines": 2
}

limit 默认为 5 并被夹紧 1..20. context_lines 默认为 2 并被夹紧 0..10.

`generate_topdrawer_png`

输入：

{
  "input_path": "examples/error-bars.top",
  "script": null,
  "base_dir": null,
  "output_path": "/tmp/output.png",
  "overwrite": false,
  "dpi": 160,
  "padding": 12,
  "crop": true,
  "background": "white"
}

提供以下之一 input_path 或 script. base_dir 仅用于内联脚本输入。 output_path 是可选的，不再是规范的切换；该工具总是返回 artifact_id 和 resource_uri 为了生成的工件包。当 output_path 省略，服务器仍使用创建保留工件时的内部临时路径。 dpi 默认为 160, padding 默认为 12 点， crop 默认为 true，以及 background 接受 white 或 transparent.

随着 crop=true，服务器修剪到PostScript BoundingBox并应用 padding.与 crop=false，服务器呈现原始PostScript页面大小并忽略 padding.

成功结果形状：

{
  "success": true,
  "format": "png",
  "message": "Generated PNG successfully.",
  "artifact_id": "tdart_20260613_123456_abcd1234",
  "resource_uri": "resource://artifacts/tdart_20260613_123456_abcd1234",
  "metadata": {
    "source_kind": "input_path",
    "dpi": 160,
    "background": "white",
    "crop_applied": true,
    "output_path_overridden": false,
    "normalized_device_config": {
      "device": "POSTSCRIPT",
      "output_key": "FILE",
      "output_value": "/tmp/topdrawer-mcp-render-ps/render.ps"
    }
  }
}

阅读 resource_uri 首先获取工件清单，然后按照其 output, source，以及 metadata 根据需要提供URI。生成的工件是临时的，不在正常范围内 resources/listThe /output 资源对每种格式保持相同的URI形状，而其MIME类型为工件特定，例如 image/png 或 application/postscriptThe 保留 /source 资源存储Topdrawer脚本的执行时间服务器实际运行。

`generate_topdrawer_postscript`

输入：

{
  "input_path": "examples/error-bars.top",
  "script": null,
  "base_dir": null,
  "output_path": "/tmp/output.ps",
  "overwrite": false
}

提供以下之一 input_path 或 script. base_dir 仅用于内联脚本输入。 output_path 是可选的，仅作为补充；规范结果是返回的工件清单URI。

成功结果形状：

{
  "success": true,
  "format": "postscript",
  "message": "Generated PostScript successfully.",
  "artifact_id": "tdart_20260613_123457_efgh5678",
  "resource_uri": "resource://artifacts/tdart_20260613_123457_efgh5678",
  "metadata": {
    "source_kind": "script",
    "output_path_overridden": false,
    "normalized_device_config": {
      "device": "POSTSCRIPT",
      "output_key": "FILE",
      "output_value": "/tmp/topdrawer-mcp-render-out/render.ps"
    }
  }
}

`get_server_runtime_info`

返回以下对象的结构化只读运行时信息：

手动搜索源路径
被跟踪的命令查找源文件
已解决 td 和 gs 用于渲染的可执行文件

当渲染工具因以下原因而失败时，将此作为第一个故障排除步骤缺少可执行文件，已损坏 PATH 分辨率或客户端MCP环境配置。

`scan_topdrawer_script`

输入：

{
  "script": "set window x 0 13 y 0 10\nset limits x 0 to 5 y 0 to 6\nplot axis\ntitle top \"Example\"\ncase \"GGGGGGG\"\nplot\n"
}

返回内联Topdrawer脚本文本的结构化首遍扫描：

识别带有行号的覆盖命令
规范化命令名称和命令类型

`scan_topdrawer_file`

输入：

{
  "input_path": "examples/sample.top"
}

返回与相同的命令发现扫描 scan_topdrawer_script，但读来自现有文件路径的脚本。扫描仪还可以识别 READ.

Topdrawer输入示例：

set symbol 1P
set order y x dx dy
100 1 0.5 10
144 2 0.5 12
196 3 0.5 14
plot

使用 generate_topdrawer_png 或 generate_topdrawer_postscript 新工作当你已经有了 .top 磁盘上的文件。

`render_topdrawer_script`

输入：

{
  "script": "set symbol 1P\nset order y x dx dy\n100 1 0.5 10\n144 2 0.5 12\n196 3 0.5 14\nplot\n",
  "base_dir": "/tmp/sample-data",
  "output_path": "/tmp/output.png",
  "overwrite": false
}

script 必须非空。 base_dir 是可选的，控制相对程度脚本内的路径，例如 set file input='dat'，已解决。当省略，相对引用使用服务器的当前工作目录。便携式网络图形输出以不透明的白色背景呈现，并修剪为带有小填充的PostScript边界框。

使用 render_topdrawer_script 当呼叫者有内联Topdrawer文本时，聊天代理转换为脚本的数据，或不转换为脚本变体的数据需要保存为持久 .top 文件第一。

兼容性渲染工具

render_topdrawer_file 和 render_topdrawer_script 在以下期间保持可用过渡到以格式为中心的曲面。他们继续生成PNG 输出并委托给较新的PNG生成核心。

`lookup_command`

输入：

{
  "command": "SYMBOL"
}

按规范命令名称或唯一别名。此工具仅返回结构化命令元数据。使用 reverse_lookup_commands 首先，当来电者从含糊的措辞开始时而不是命令名。

`reverse_lookup_commands`

输入：

{
  "query": "polar plot",
  "limit": 5
}

返回一个简短查询的规范命令标题的小排名列表。 limit 默认为 5 并被夹紧 1..20.以前用过这个 lookup_command 当呼叫者知道意图但不知道顶层抽屉时命令名称尚未确定。使用 search_manual 只有当排名的候选人和结构化的指挥指导仍然不够。

`list_manual_samples`

输入：

{
  "category": "histogram",
  "command": "HISTOGRAM",
  "query": "basic",
  "limit": 20
}

所有过滤器都是可选的。 category 匹配一个精心策划的样本类别。 command 火柴 primary_commands 案件不敏感。 query 执行a 仅对样本元数据进行不区分大小写的子字符串搜索。此工具返回仅元数据；它不返回示例脚本文本。

`get_manual_sample`

输入：

{
  "sample_id": "scatter-error-bars"
}

按id返回一个精选的示例元数据条目。此工具返回元数据只有；示例脚本文本仍然不在当前MCP表面的范围内。

MCP资源

`resource://commands/index`

返回所有已审阅命令条目的JSON发现元数据。每个条目包括：

command
aliases
kind
parent_command
section
title
uri

`resource://commands/{command}`

为规范资源返回一个JSON格式的已审核顶级命令条目路径。

`resource://commands/{parent}/{command}`

为规范资源返回一个JSON格式的已审阅嵌套命令条目路径。别名仍受支持 lookup_command，但是这些资源模板只需要规范路径。

示例：

resource://commands/title
resource://commands/set/order
resource://commands/title/case

MCP提示

`inspect_topdrawer_script`

提示参数：

script_text 可选的
input_path 可选的
goal 可选的

提示恰好需要以下之一 script_text 或 input_path 并指导代理人通过：

scan_topdrawer_file | scan_topdrawer_script -> lookup_command -> search_manual if needed

`discover_topdrawer_command`

提示参数：

query 必需的
context 可选的

此提示将引导代理完成当前短语以命令工作流：

reverse_lookup_commands -> lookup_command -> search_manual if needed

测试

运行完整的测试套件：

uv run --extra test pytest

只运行Python单元测试：

uv run --extra test pytest -m unit

仅运行基于检查器的集成测试：

uv run --extra test pytest -m integration

集成测试使用 npx @modelcontextprotocol/inspector 并要求 Node.js与 npx 可用的 PATH.

使用说明

最上层的mcp

范围

数据

预处理

跑

MCP客户端配置

渲染先决条件

第一步故障排除

MCP工具

search_manual

generate_topdrawer_png

generate_topdrawer_postscript

get_server_runtime_info

scan_topdrawer_script

scan_topdrawer_file

render_topdrawer_script

兼容性渲染工具

lookup_command

reverse_lookup_commands

list_manual_samples

get_manual_sample

MCP资源

resource://commands/index

resource://commands/{command}

resource://commands/{parent}/{command}

MCP提示

inspect_topdrawer_script

discover_topdrawer_command

测试

相关 MCP

iOS/macOS 构建 MCP 服务器与命令行工具

小红书内容访问服务

生物医学数据检索命令行与MCP服务

Windows命令行服务器

进程执行工具

MCP服务器管理工具