Twincat Knowledge MCP Server

TwinCAT知识MCP服务器

模型上下文协议（MCP）服务器，提供对TwinCAT 3文档的语义搜索访问。该项目包括将PDF转换为Markdown、生成嵌入和在GitHub页面上托管可搜索的API的工具。

概述

该项目为TwinCAT 3文档提供了一个完整的语义搜索解决方案：

1. PDF转换：将290个TwinCAT 3文档PDF从Beckhoff转换为Markdown格式
2. 嵌入生成：使用转换器模型生成语义嵌入
3. 搜索API：使用Transformers.js在GitHub页面上托管搜索API
4. MCP服务器：为Cursor和LM Studio提供MCP兼容接口

建筑

[Generate Embeddings] → Push to GitHub
            ↓
[GitHub Pages] → Transformers.js API
            ↓
[Local MCP Server] → Returns to Cursor/LM Studio

特性

• 语义搜索：使用基于转换器的嵌入进行自然语言搜索
• 持久缓存：智能缓存系统，后续搜索速度提高90%
• GitHub页面API：使用Transformers.js免费、无限制地托管
• 元数据：用于高级过滤的结构化YAML frontmatter
• 类别支持：按产品、类别、版本等搜索
• 无需GPU：MCP服务器在CPU上运行，可在任何机器上工作

快速开始

本地安装

1. 克隆仓库:

git clone https://github.com/njfsmallet-eng/twincat-knowledge-mcp-server.git
cd twincat-knowledge-mcp-server

1. 安装依赖项:

npm install

1. 构建项目:

npm run build

这将TypeScript编译为JavaScript dist/ 目录。这 dist/ git中没有跟踪文件夹，因此您需要在克隆后进行构建。

备注：只有修改源代码时才需要重新生成。编译 dist/ 文件不会提交到git。

1. 添加到您的Cursor/LM Studio mcp.json:

选项A：使用编译的CommonJS（推荐）

{
  "mcpServers": {
    "twincat-knowledge": {
      "command": "node",
      "args": ["C:\\Users\\YourUsername\\path\\to\\twincat-knowledge-mcp-server\\dist\\index.js"],
      "env": {}
    }
  }
}

选项B：直接使用TypeScript

{
  "mcpServers": {
    "twincat-knowledge": {
      "command": "npx",
      "args": ["-y", "tsx", "C:\\Users\\YourUsername\\path\\to\\twincat-knowledge-mcp-server\\src\\index.ts"],
      "env": {}
    }
  }
}

备注：将路径替换为您的实际存储库位置。使用双反睫毛(\\)对于Windows路径。

不同平台的配置

该配置在所有兼容平台上的工作方式相同：

• 光标：使用 mcp.json 用户目录中的文件（通常 C:\Users\YourUsername\.cursor\mcp.json 在Windows上）
• LM 工作室：使用相同的MCP服务器配置格式

这两个平台都支持此服务器使用的标准MCP stdio协议。

用法

使用MCP服务器

在Cursor或LM Studio中配置后，使用 search_knowledge 工具：

"Describe what TwinCAT Scope is and its main features."

可用过滤器：

• category：通信、PLC、运动控制等。
• product：TF6100、TC3、TE1000等。
• top_k：结果数（默认值：5）

缓存系统

MCP服务器包括一个智能缓存系统，可显著提高性能：

• 第一个电话：下载并缓存所有数据（约16秒）
• 后续通话：从缓存加载（约1.6秒）
• 性能提升：初始缓存填充后速度提高90%
• 缓存位置: .cache/ 项目根目录中的目录
• 持久：缓存在MCP服务器会话之间存活
• 自动：无需手动配置

缓存内容：

• Xenova嵌入模型（~50 MB）
• 文档块（42314个块）
• 预先计算的嵌入（压缩约57 MB）

测试搜索API

您可以直接在浏览器中测试搜索功能，网址为： https://njfsmallet-eng.github.io/twincat-knowledge-mcp-server/

此web界面允许您：

• 测试语义搜索查询
• 查看TwinCAT文档中的实时结果
• 在配置Cursor或LM Studio之前，请验证API是否正常工作

文件结构

twincat-knowledge-mcp-server/
├── src/                         # TypeScript source
│   ├── index.ts                # MCP server
│   ├── types.ts                # Type definitions
│   ├── github-pages-client.ts  # API client
│   └── cache-manager.ts        # Cache management
├── dist/                        # Compiled JavaScript (CommonJS)
│   ├── index.js                # Compiled MCP server
│   └── *.js                     # Other compiled files
├── scripts/                     # Python scripts
│   ├── chunking.py             # Text chunking
│   ├── generate_embeddings.py  # Embedding generation
│   └── README.md               # Scripts documentation
├── gh-pages/                    # GitHub Pages files
│   ├── index.html              # API interface
│   └── search.js               # Transformers.js search
├── embeddings/                  # Generated embeddings
│   ├── chunks.json             # Chunks with metadata
│   ├── embeddings.npy.gz       # Compressed vectors
│   └── metadata.json           # Generation stats
├── docs/                        # Converted markdown docs
├── .cache/                      # Persistent cache (auto-created)
│   ├── chunks.json             # Cached documentation chunks
│   ├── embeddings.npy.gz       # Cached embeddings
│   └── model/                  # Xenova model cache
│       └── Xenova/
│           └── all-MiniLM-L6-v2/
├── .github/workflows/           # CI/CD
│   └── deploy-pages.yml        # GitHub Pages deployment
├── package.json                 # Node.js config
├── tsconfig.json               # TypeScript config
└── requirements.txt            # Python dependencies

依赖项

Python（仅用于嵌入生成）：

• sentence-transformers -嵌入式变压器模型
• torch -PyTorch
• numpy -数值运算
• pyyaml -YAML解析
• tqdm -进度条

备注：Python依赖项只需要生成嵌入。MCP服务器本身只需要Node.js。

Node.js：

• @modelcontextprotocol/sdk -MCP协议
• @xenova/transformers -Transformers.js用于嵌入
• typescript -TypeScript编译器（用于构建）

该项目将TypeScript编译为CommonJS，以实现最佳的Node.js兼容性。

建筑细部

嵌入生成

• 模型: sentence-transformers/all-MiniLM-L6-v2 （384个维度）
• 格式：用gzip压缩的Float32 NumPy数组
• 尺寸：所有文档压缩约57 MB
• 备注：嵌入是预先生成的，并托管在GitHub Pages上。MCP服务器不需要任何GPU或Python依赖项来运行。

搜索API

• 前端：浏览器中的Transformers.js
• 模型: Xenova/all-MiniLM-L6-v2 ONNX（量化）
• 延迟：每次查询约500ms-1
• 缓存：用于模型缓存的IndexedDB

MCP服务器

• 运输标准： stdio
• 兼容性：光标，LM工作室（已测试）
• 模块系统：CommonJS（从TypeScript编译而来）
• 语言：TypeScript源代码，编译为JavaScript
• 本地安装：直接克隆和配置
• 缓存系统：基于磁盘的持久缓存可实现最佳性能
• 演出：初始缓存填充后速度提高90%

本地使用

需求

• Node.js: >=18.0.0
• TypeScript：>=5.9.0（用于建筑）
• 依赖项：只需要MCP SDK和Transformers.js
• 尺寸：约160 MB（包括嵌入和文档）
• 缓存：额外约110 MB用于永久缓存（自动创建）
• 构建：运行 npx tsc 将TypeScript编译为CommonJS dist/ 目录
• 文件：总共338个文件

许可证

MIT许可证