Td Docs MCP

TD-DOCS-MCP

一个MCP（模型上下文协议）服务器，为AI编码助手提供TouchDesigner文档。这为TouchDesigner项目提供了更好的Python脚本建议和UI建议。

特性

• 完整文档访问权限：从docs.derivative.ca中抓取的文档，包括所有运算符类型（TOP、CHOP、DAT、SOP、MAT、COMP）、Python基类和特定于运算符的Python类（例如。， BlurTOP_Class, ScriptCHOP_Class)
• 模糊搜索：即使有不精确的查询，也能找到相关文档
• Python类查找：快速访问TouchDesigner Python API文档
• MCP集成：可与Claude Code、Claude Desktop、VS Code+Copilot、Cursor和其他MCP兼容工具配合使用

通过VS Code+Copilot有效使用MCP

MCP工具是反应性的——Copilot在认为它们相关时会调用它们。为了充分利用它们：

• 在关于TouchDesigner上下文的提示中要明确。与其说“我如何模糊图像”，不如说“我在TouchDesigner DAT执行脚本中工作，需要通过Python更改模糊TOP上的大小参数。”这会触发Copilot搜索文档，而不是产生幻觉。
• 在编写代码之前，让它先查找一下。类似于“查找Blur TOP参数及其Python类，然后编写一个脚本…”在任何代码生成之前强制执行两次MCP调用。
• 医生预防幻觉的关键用例：

- 参数名称——TD参数具有特定的标识符（moviefilein1.par.file不是.filename）。文档具有每个ParamName identifier 上市的。 - Python类方法——知道脚本上有什么CHOP_class、CHOP_Classes和OP_class可以防止发明方法名 - 回调签名——DAT执行、CHOP执行、Panel执行都有AI工具经常出错的特定回调签名 - 节点接线——“操作员输入/输出”部分记录了哪些操作员接受哪些输入以及接受多少输入 - 烹饪行为——当食物烹饪时，时间切片等。——人工智能模型自信地制造的东西

快速开始

先决条件

• Python 3.10或更高版本
• 紫外线 包管理器（推荐）或pip

安装

1. 克隆存储库：

   git clone https://github.com/yourusername/td-docs-mcp.git
   cd td-docs-mcp

1. 使用uv安装依赖项：

   uv sync

1. \[可选\]抓取TouchDesigner文档。最近已经有爬行 td_docs/ 目录，因此此步骤是可选的，除非您想要最新的文档或想要自定义流程。爬虫从官方TD文档中获取文档，并将其保存为markdown文件 td_docs/.使用以下命令运行爬虫：

   uv run python -m td_docs_mcp.crawler

这创建了一个 td_docs/ 文件夹中的所有文档都是干净的markdown文件。

1. 配置您的MCP客户端（请参阅 配置 在......下面

配置

克劳德代码

增添 ~/.claude.json:

{
  "mcpServers": {
    "td-docs-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/td-docs-mcp", "run", "td-docs-mcp"]
    }
  }
}

克劳德桌面版

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "td-docs-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/td-docs-mcp", "run", "td-docs-mcp"]
    }
  }
}

光标/风帆

看 config/cursor.md 用于光标和风帆配置。

VS代码与GitHub Copilot

VS Code原生支持MCP服务器。创建 .vscode/mcp.json 在您的项目中：

{
  "servers": {
    "td-docs-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/path/to/td-docs-mcp", "run", "td-docs-mcp"]
    }
  }
}

看 config/vcode_copilot.md 有关详细设置，包括Windows路径、环境变量和使用提示。

用法

配置后，您的AI助手将可以访问这些工具：

search_touchdesigner.docs

搜索所有TouchDesigner文档：

"How do I use a Noise TOP?"
"What parameters does Movie File In have?"
"Python OP class methods"

read_operator_doc

阅读特定的文档文件（通常在搜索后）：

"Read the full documentation for TOPs/Noise_TOP.md"

列表_类别

列出可用的文档类别：

"What TouchDesigner documentation categories are available?"

get_python类

快速查找Python类文档：

"Show me the TOP Python class documentation"
"What methods does the OP class have?"

查询示例

以下是您的AI助手现在可以更好地处理的一些示例查询：

1. 操作员基本用法:

> “如何使用噪波顶部创建噪波模式？”

1. Python脚本:

> “如何在TouchDesigner中使用Python更改参数？”

1. 复杂的任务:

> “我正在使用TOP中的电影文件。我需要使用Python做两件事： > > 1. 编写对“file”参数的更改脚本以加载新视频。 > 1. 获取加载视频的实际宽度和高度（像素）。 > 我该如何编写这段代码？"

爬行器选项

爬虫分三个阶段运行：

1. 操作员类别 --抓取TOP、CHOP、DAT、SOP、POP、MAT和COMP的索引页
2. Python参考 --从TouchDesigner_Python_classes索引中抓取基类（OP_Class、TOP_Class等）
3. 运算符Python类 --扫描已保存的操作员文档，查找指向操作员特定类页面的链接（例如。， BlurTOP_Class, ScriptCHOP_Class)并将每个类别抓取到其匹配的类别目录中，以及引用它的操作员文档

所有阶段都有恢复功能——磁盘上已有的文件会自动跳过。

# Crawl all documentation (all three stages)
uv run python -m td_docs_mcp.crawler

# Crawl specific categories only
uv run python -m td_docs_mcp.crawler -c TOPs CHOPs Python

# Limit pages per category/stage (for testing)
uv run python -m td_docs_mcp.crawler --limit 5

# Only crawl operator Python class pages (stage 3 only, requires existing operator docs)
uv run python -m td_docs_mcp.crawler --classes-only

# Skip the operator Python class crawl (stages 1 & 2 only)
uv run python -m td_docs_mcp.crawler --skip-classes

# Re-crawl pages that previously returned 403/error content
uv run python -m td_docs_mcp.crawler --retry-failed

# Custom output directory
uv run python -m td_docs_mcp.crawler -o /path/to/docs

Markdown清理工具

爬虫会在保存每个文件时自动进行清理，因此不再需要单独的清理步骤。独立清理程序对于重新处理现有文件仍然有用，例如在添加新的清理规则后：

# Re-clean all existing docs
uv run python -m td_docs_mcp.cleaner

# Clean a single file
uv run python -m td_docs_mcp.cleaner -f td_docs/TOPs/Blur_TOP.md

# Preview changes without writing (dry run)
uv run python -m td_docs_mcp.cleaner --dry-run

清洁剂采用以下修复方法：

• 删除wiki工件(From Derivative, [edit] 链接， Jump to navigation，空标题）
• 剥去 ## Contents TOC部分
• 修复了丢失部分标题的问题 ## 转换过程中的前缀
• 将同一页面的绝对锚点链接转换为相对锚点链接 #fragment 本地标记导航链接
• 清理Python类文档中的区块引用格式
• 删除冗余的运算符族页脚（链接列表和术语表）
• 将参数行格式化为正确的标记项目符号列表
• 将通用wiki页面（术语表、教程等）重新定位到共享 General/ 目录
• 缩小过多的空白行并修剪尾随的空白

测试

使用MCP检查员进行测试

npx @modelcontextprotocol/inspector uv --directory . run td-docs-mcp

运行单元测试

uv run pytest

项目结构

td-docs-mcp/
├── pyproject.toml              # Project configuration
├── README.md                   # This file
├── CONTRIBUTING.md             # Contribution guidelines
├── LICENSE                     # MIT License
├── src/
│   └── td_docs_mcp/
│       ├── __init__.py
│       ├── server.py           # MCP server implementation
│       ├── crawler.py          # Documentation scraper
│       └── cleaner.py          # Post-crawl markdown cleanup
├── td_docs/                    # Scraped docs (gitignored)
├── skills/
│   └── TD_SKILLS.md            # Best practices context
└── config/
    ├── claude_code.md          # Claude Code setup
    ├── claude_desktop.md       # Claude Desktop setup
    ├── cursor.md               # Cursor/Windsurf setup
    └── vscode_copilot.md       # VS Code notes

环境变量

• TD_DOCS_MCP_DOCS_DIR：文档目录的自定义路径（默认为 td_docs/ 在项目根中）

贡献

看 贡献.md 作为指导方针。

许可证

MIT许可证-请参阅 许可证 了解详情。

致谢

• TouchDesigner 按衍生品
• 模型上下文协议 通过Anthropic
• Crawl4AI 用于网页抓取