内容
# CODESYS MCP 服务器
CODESYS 开发系统 V3 的模型上下文协议（MCP）服务器。为 MCP 客户端提供精选的 CODESYS 指导、结构化文本编写帮助、可搜索的本地 PDF 文档，以及可选的允许列表中官方 CODESYS 页面的实时查找。
服务器可以通过 HTTP 在 `/mcp` 上运行，也可以通过 stdio 进行直接 CLI 和代理集成。官方页面被总结和引用，而不是复制到项目中。主要的官方来源包括 [CODESYS 在线帮助](https://content.helpme-codesys.com/) 和 [CODESYS 示例](https://content.helpme-codesys.com/en/CODESYS%20Examples/_ex_start_page.html)。
## 工具
- `search_codesys_docs`：搜索精选和/或官方的 CODESYS 指导。
- `get_codesys_topic`：解释已知的主题，例如 POU、功能块、定时器、任务、变量、库、调试或结构化文本。
- `codesys_writing_guidance`：为请求的任务提供实用的 CODESYS 和结构化文本设计指导。
- `list_codesys_pdfs`：列出在配置的 PDF 文件夹中可用的 PDF 文档。
- `search_codesys_pdfs`：搜索从本地 PDF 文档中提取的文本。
- `get_codesys_pdf`：返回从特定的本地 PDF 文档中提取的文本。
- `get_codesys_page`：获取任何允许列表中官方 CODESYS 文档 URL 的全文内容。
- `crawl_codesys_help`：爬取和索引 CODESYS 帮助网站，以提供可搜索的文档。
## 功能
- 搜索精选的 CODESYS 指导，获取概念、语法和工作流帮助。
- 解释常见的 CODESYS 主题，例如 POU、功能块、定时器、任务、变量、库、调试和结构化文本。
- 提供实用的结构化文本和项目结构指导。
- 搜索本地 PDF 手册和放置在 `docs/pdfs/` 中的笔记。
- 获取和总结允许列表中官方 CODESYS 文档页面。
- 爬取官方帮助网站，以建立可搜索的索引。
## 人工安装
当您想在自己的机器上运行服务器时使用。
先决条件：
- Node.js 20 或更新版本
- `npm`
从全新克隆开始：
```bash
npm install
cp .env.example .env
npm run build
```
启动 HTTP 服务器：
```bash
npm start
```
或启动 stdio 服务器：
```bash
npm run start:stdio
```
默认情况下，HTTP 服务器监听 `http://0.0.0.0:3000/mcp`。
## 为 LLM 或代理安装
> **AI 代理？** 阅读 [`agent.md`](agent.md) — 它包含专门为您编写的完整、分步骤的自我安装指南。从那里开始。
当 LLM 被指示将其自身连接到服务器作为 MCP 客户端时，请使用此部分。
建议给 LLM 的指令：
```text
阅读存储库根目录中的 agent.md。它包含将此 MCP 服务器安装到您自己的确切步骤。
```
1. 首先构建项目：
```bash
npm install
npm run build
```
2. 优先使用 stdio 传输进行本地代理集成。
3. 使用本地构建输出将服务器添加到客户端：
```bash
claude mcp add --transport stdio codesys-docs -- node ./dist/src/cli.js --stdio
```
4. 如果客户端需要 HTTP，请启动服务器并注册端点：
```bash
npm start
```
```bash
claude mcp add --transport http codesys-docs http://localhost:3000/mcp
```
5. 如果代理只能从已发布的包工作，请使用：
```bash
claude mcp add --transport stdio codesys-docs -- npx -y codesys-mcp-server --stdio
```
对于 Codex CLI：
```bash
codex mcp add codesys-docs -- node ./dist/src/cli.js --stdio
```
## 快速入门
```bash
npm install
cp .env.example .env
npm run build
npm start
```
服务器默认监听 `http://0.0.0.0:3000/mcp`。
## Docker
```bash
docker compose up --build
```
编排文件将 `./docs/pdfs` 挂载到容器中作为只读文件，因此您可以添加本地 PDF 文件而无需重建镜像。
## PDF 文件夹
将 CODESYS 手册、供应商 PDF、项目笔记、数据表或导出的文档放在：
```text
docs/pdfs/
```
MCP 服务器从该文件夹中的 `.pdf` 文件中提取文本，并通过以下方式使其可用：
- `search_codesys_docs`，使用 `sourceMode: "pdf"` 或 `sourceMode: "all"`
- `list_codesys_pdfs`
- `search_codesys_pdfs`
- `get_codesys_pdf`
PDF 文本提取适用于可搜索的文本 PDF。扫描的仅图像 PDF 可能返回很少或没有内容，除非已经应用了 OCR。提取的文本可能会省略图表、截图、格式和一些表格，因此应根据原始 PDF 验证重要的工程细节。
## 配置
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `PORT` | `3000` | HTTP 端口。 |
| `HOST` | `0.0.0.0` | 绑定主机。 |
| `OFFICIAL_LOOKUP_ENABLED` | `true` | 启用实时官方 CODESYS 页面查找。 |
| `OFFICIAL_LOOKUP_TIMEOUT_MS` | `3500` | 每个官方页面的获取超时时间。 |
| `OFFICIAL_LOOKUP_CACHE_TTL_SECONDS` | `3600` | 官方页面的内存缓存 TTL。 |
| `PDF_SEARCH_ENABLED` | `true` | 启用本地 PDF 的文本提取/搜索。 |
| `PDF_DOCS_DIR` | `docs/pdfs` | 扫描 `.pdf` 文件的文件夹。 |
| `PDF_MAX_TEXT_CHARS` | `200000` | 每个 PDF 存储的最大提取文本字符数。 |
## CLI 使用
```bash
# HTTP 服务器（默认）
node dist/src/cli.js
npm start
# Stdio 服务器（用于 Claude Code / Codex CLI MCP 集成）
node dist/src/cli.js --stdio
npm run start:stdio
```
## 验收检查
```bash
npm test
npm run build
curl http://localhost:3000/healthz
```
