Public-Regulation-MCP-Builder

# PR MCP 构建工具 ## 公共机构法规 MCP 构建工具 [](#windows-执行版) [](pyproject.toml) [](#ai-程序与mcp-连接) [](https://github.com/chrisryugj/kordoc) [](#处理结构) [](LICENSE) PDF、HWP、HWPX、DOCX 格式的公共机构法规，按照 **机构 → 法规 → 修订版本 → 章节条款** 结构整理，并仅将人工批准的内容纳入检索索引和 MCP 响应。这是用于 Windows 的构建工具。 并非简单地将所有句子切分成相同大小以进行相似度搜索。 首先缩小法规名称和目录范围，然后查找最新有效修订版的条款，如有必要甚至追溯之前的修订记录。 如果同一机构的修订版再次被添加，读取文档前部的制定、修订历史和生效日期，并将其与现有法规系列连接成新版本。 ## 20 秒使用流程 <p align="center"> <img src="docs/assets/pr-mcp-builder-demo.gif" alt="PR MCP Builder 从机构选择到 MCP 连接的示例使用流程" width="960" /> </p> <p align="center"><a href="docs/assets/pr-mcp-builder-demo.gif">在新窗口中查看 GIF</a></p> > [!IMPORTANT] > 目前是一个正在开发的、基于公开源码的开发版。 Streamlit 界面仅适用于本地管理员，在实际机构应用之前，需要根据文档格式、修订历史、导出范围和安全策略进行验证。 请勿将未经批准的区块纳入检索索引和 MCP 响应。 ## 最简单的运行方式 ### Windows 执行版 如果使用发布 ZIP，请执行以下三个步骤： 1. 将 `PR-MCP-Builder-Windows-x64-<版本>.zip` 解压到普通文件夹中。 2. 双击文件夹中的 **`PR MCP Builder.exe`**。 3. 使用浏览器自动打开的本地界面。 工作数据默认存储在 `%LOCALAPPDATA%\PR MCP Builder\data` 中。 如果端口 `8501` 被占用，启动器将自动选择下一个可用端口。 ### 从源代码运行 安装 Python 3.11 或更高版本后，在项目文件夹中双击 **`START_HERE.bat`**。 首次运行需要互联网连接来安装虚拟环境和包。 默认地址是 `http://127.0.0.1:8501`。 如果要从终端启动，请使用以下命令。 为防止外部暴露，本地界面仅绑定到 `127.0.0.1`。 ```powershell .\.venv\Scripts\python.exe -m streamlit run frontend\streamlit_app.py --server.address 127.0.0.1 ``` 从源代码运行时，工作数据存储在项目文件夹的 `data\` 中。 Windows 执行版使用上述 `%LOCALAPPDATA%\PR MCP Builder\data`。 如果只需要检查运行条件，请使用以下命令。 ```powershell .\START_HERE.bat --check ``` ## 处理结构 ```text 选择机构 → 上传法规文件 → 识别法规名称、修订日期、生效日期、修订历史 → 法规/版本/目录/条款分层索引 → AI 建议审查 + 人工原始文本对比 → 仅最新有效版本经批准后纳入检索和 MCP 响应 → Codex、Claude 本地连接或 ChatGPT、Claude HTTPS 连接 ``` - 每个机构的工作空间、待处理文件、项目存储、批准数据和 MCP 输出分别存储。 - 即使在同一机构内，法规 ID 和版本 ID 也被分开，以保存旧修订版。 - 未经人工批准的区块不纳入检索索引和 MCP 响应。 - 重新加载所有法规时，即使机构、法规名称和修订历史相同，也会重建相同的分层结构。 - MCP 服务器名称不是固定的。 用户需要在创建界面输入，界面示例不会自动应用。 - 存储位置也不是固定的。 客户端的绝对路径将反映在用户选择的文件夹中。 ## 界面使用顺序 按照以下界面顺序，从选择机构到连接 MCP。 ### 1. 选择机构 在第一个界面中，只需输入机构名称或选择已注册的机构。 在此阶段，不会显示已保存的项目、API 密钥、法规文件或 MCP 设置。 选择机构后，在打开的第二个仪表板中，可以使用该机构的项目存储和加载。  选择机构后，文档、批准记录、搜索范围和 MCP 输出将仅限于所选机构范围。 如果加载其他机构的已保存项目或文档 ID，它们将被阻止在界面中，因为它们与当前机构不匹配。  ### 2. 上传和预处理法规 在 `① 上传文档进行预处理` 中，选择 PDF、HWP、HWPX 或 DOCX 文件。 可以一次上传多个文件，它们将被分类到法规系列和修订版本顺序中。  自动识别不仅查看文件名。 它优先考虑文档前部的 `制定`、`修订`、`全部修订`、生效日期和修订历史，以确定法规名称和版本。 对于特殊文档，可以在 `手动修改自动识别值` 中进行补充。 在预处理期间，实际工作阶段和处理计数以进度条显示。 对于大型综合法规书籍，进度条将继续更新，显示法规数量、结构存储、区块存储、检查结果存储、导出和经过的时间。   ### 可选功能：外部 AI 审查 AI 审查不是必需的前置流程，而是一个可选功能，默认情况下处于关闭状态。 当处于关闭状态时，不会将内容发送到外部进行处理，而只使用本地解析器和人工审查。 只有在打开的情况下，才会将具有质量警告的条款、表格、附表和损坏字符等可疑部分发送到所选提供商以获取审查草稿。 支持的提供商如下。 | 提供商 | 输入项 | 模型选择 | | --- | --- | --- | | OpenAI | API 密钥，API 地址 | 推荐 `gpt-4.1-mini`，其他模型或自定义输入 | | Azure OpenAI | 资源端点，API 密钥 | 输入机构 Azure 部署名称 | | Anthropic Claude | API 密钥，API 地址 | Claude 模型列表或自定义输入 | | OpenAI 兼容 API | 内部/本地 API 地址，可选密钥 | 自定义 Ollama/内部网关模型 ID | 在 OpenAI 中，基于平衡速度和成本，`gpt-4.1-mini` 被显示为此产品的默认推荐模型。 此模型支持 Chat Completions 和结构化输出。 有关详细信息，请参阅 [OpenAI 官方 GPT-4.1 mini 文档](https://developers.openai.com/api/docs/models/gpt-4.1-mini)。  在 README 截图中，没有输入外部 API 密钥，因此没有执行实际的 AI 文本修改，本地解析器突出显示的风险部分是审查草稿的重点。 因此，没有 AI 审查结果或建议并不表示错误。 AI 审查不是自动批准功能，使用结果时，仍需要人工将原始文本与修改后的结果进行对比。 ### 3. 结果确认 检查结构节点数、区块数、问题、质量分数和识别的法规/版本信息。 包含 140 多个法规的文件首先创建分层索引，以便按法规和目录缩小范围，然后进入条款。 上传多个法规文件时，将首先显示所有默认选定的 `要一起处理的法规目录`。 按下 `打开法规` 仅加载所选法规的详细数据，因此不需要每次都在屏幕上展开整个文档集。 在所选法规中，可以检查以下内容。 - 当前法规与直接/前/后修订版的关系 - 目录和区块位置、原始页码、置信度和警告 - 已选区块的原始文本和预处理结果左右对比，直接/当前/下一个区块上下文 选定的法规在结果确认、审查/批准和 MCP 生成阶段作为一个工作单元被保留。 仅当您想在本 MCP 中排除某些法规时，请取消选中它们。  ### 4. AI 和人工审查 审查可以逐个区块进行，也可以全部完成后一次性完成。 - `完成整个法规的 AI 审查`：无论当前状态如何，一次性确认整个 AI 建议。 - `完成整个法规的人工确认`：一次性完成整个区块的人工确认。 - `完成剩余部分的人工审查`：保留已有的 `已反映` / `未反映` 决定，仅对未确定的 AI 建议完成审查。 - `完成剩余部分的人工审查`：保留已确认的区块，继续完成未确认区块的审查。 因此，即使先详细修改某些区块，然后仅对剩余部分进行批量审查，先前的工作也不会被覆盖。 AI 批量审查不能代替最终批准，在批准之前，仍需要人工检查原始文本和修改后的结果。   按下 `批准并索引`，只有已完成审查的区块才进入批准索引。 请在界面上确认批准的最新有效版本和 MCP 上暴露的记录数量是否一致。 此顺序是 **仅批准的法规才能生成为 MCP 数据** 的必要条件。  ### 5. 选择 MCP 范围和连接目标 在 `④ 生成 MCP 和 AI 连接` 中，选择数据范围。 - `所选法规 N 个`：将所选法规无缝地纳入单个 MCP 中。 这是默认选择。 - `当前年度法规`：仅包括目录中当前打开的法规。 - `选择机构的所有批准法规`：包括当前机构的所有批准和最新有效法规。 在 `选择 N 个法规` 时，可以在表中检查每个法规的批准区块数量和 MCP 暴露记录数量。如果没有完成审查、批准和索引，则不会创建 MCP 生成按钮。 接下来，选择要使用的集成 ChatGPT Desktop、Codex CLI、Claude Desktop、Claude Code、ChatGPT Web 或 Claude HTTPS 客户端。 最新版本的 ChatGPT Desktop 集成 Codex 插件 MCP 设置，可以通过本地 stdio 连接。  ### 6. 生成 MCP 文件包 输入 `MCP 名称`，确认存储文件夹，然后单击 `创建文件包以用作 MCP` 按钮。 文件夹名称中生成的值仅作为输入示例显示，不会自动应用。 如果不输入名称，则无法创建 ZIP、BAT 和连接设置，只能使用输入的名称作为 AI 应用程序的 MCP 名称注册。 批准的数据复制、层次结构 DB 创建、连接设置编写、脚本生成和 ZIP 压缩的进度将根据实际完成项目显示。 请勿直接指定可能限制写入权限的位置，例如 `C:\` 根目录。 请在文档、桌面或用户选择的文件夹中保存。   生成的目录中包含用于双击的客户端特定文件。  ## 大量法规的进度显示 包含 800 页或 140 多个法规的综合文档可能需要更长时间才能分页和保存。 以下工作将保持进度窗口，而不是在空白屏幕上无响应。 - 预处理：当前文件、内部法规编号、结构/区块/检查/导出计数和经过的时间 - 进入下一步：后台预读文档/区块/目录/索引状态的实际进度和心跳 - 完整/剩余审查：已完成区块和总区块数 - 批准/索引：批准的区块数、索引阶段和经过的时间 - MCP 生成：批准的数据复制、分层 DB 和 BM25 生成、连接文件编写、ZIP 压缩字节数 内部库在某些部分可能不会立即提供详细信息。 在这种情况下，`正在工作...`、经过的时间和上一次完成的阶段将每 0.5 秒更新一次。 估计的进度不会早于实际测量值完成，并且仅在接收到实际完成事件后才达到 100%。  ## 本地连接 非开发人员不需要直接编辑 PowerShell 脚本或 JSON 设置。 1. 完全关闭要连接的 AI 应用程序。 2. 在 MCP 生成文件夹中，双击要使用的应用程序的批处理文件。 3. 双击 `检查连接状态.bat` 以检查是否没有错误。 4. 重新启动 AI 应用程序并打开新的对话。 5. 在新的对话或任务中，使用 `使用输入的名称 MCP 调用已注册的法规列表。` | 对象 | 用户运行的文件 | 程序处理的设置 | | --- | --- | --- | | ChatGPT Desktop (集成 Codex) | `连接到 ChatGPT Desktop.bat` | 备份 `%USERPROFILE%\.codex\config.toml` 并注册插件 MCP 的名称、命令、参数和工作文件夹 | | Codex CLI 兼容 | `连接到 Codex.bat` | 在用户 Codex 设置中注册当前 MCP 服务器名称和实际文件夹路径 | | Claude Desktop | `连接到 Claude Desktop.bat` | 备份 `%APPDATA%\Claude\claude_desktop_config.json` 然后合并 | | Claude 代码 | `连接到 Claude 代码.bat` | 注册 `claude mcp add ...` 形式的本地 stdio | 每个应用程序使用相同的批准数据，但设置文件和注册方法不同，因此连接按钮也分开。 集成 ChatGPT Desktop 应用程序完全退出后，运行 BAT 文件并重新启动，`设置` > `插件` > `MCP` 中将显示输入的名称和实际执行路径。 用户无需直接输入命令或参数。 使用相同的 MCP 名称重新生成并运行 BAT 文件时，不会重复添加现有项目，而是用新的路径和设置替换。 ## ChatGPT 网页连接 上面集成的 ChatGPT Desktop 本地插件与 ChatGPT 网页应用连接是分开的。 ChatGPT 网页的自定义 MCP 应用程序需要可从 Internet 访问的远程 MCP 端点。 不能直接将 `localhost` 或本地 stdio 连接到 ChatGPT 网页。 1. 在创建界面中选择 `ChatGPT HTTPS` 或 `ChatGPT 安全隧道`。 2. 对于 HTTPS 方法，请输入公开的基本地址。 界面将显示最终的 `/mcp` 地址。 3. 将 MCP 包部署到批准的服务器并配置 TLS 和身份验证。 4. 在 ChatGPT 的 `设置` 或工作区设置中，打开 `应用` > `创建`。 5. 输入生成的 HTTPS MCP URL，扫描工具后创建应用。 6. 在新的对话中，选择具有输入的 MCP 名称的应用或通过 `@MCP 名称` 指定，然后调用 `使用 MCP 名称显示注册的法规列表。`  根据计划和工作区管理员策略，可能看不到开发人员模式或自定义应用菜单。 最新条件请参考 OpenAI 官方文档中的 [开发人员模式和自定义 MCP 应用](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta) 和 [ChatGPT 中的应用](https://help.openai.com/en/articles/11487775-connectors-in-chatgpt)。 ## Claude 连接 同一台 PC 上的 Claude Desktop 和 Claude Code 使用本地 stdio 方法最简单。 只需运行上表中的批处理文件即可。 要在 Claude 网页或远程环境中使用，请按照以下顺序连接。 1. 在创建界面中选择 `Claude HTTPS` 并输入公开的 HTTPS 基本地址。 2. 将生成的 MCP 包部署到批准的服务器。 3. 在 Claude 的 `设置` > `连接器` 中添加自定义连接器。 4. 注册最终的 `/mcp` URL 和必要的身份验证信息。  本地 Claude Desktop 配置和远程连接器配置是分开的。 请勿将远程 MCP URL 作为本地 stdio 项目插入 `claude_desktop_config.json`。 有关详细信息，请参阅 Anthropic 官方文档中的 [本地 Claude Desktop MCP](https://support.anthropic.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop) 和 [远程自定义连接器](https://support.anthropic.com/en/articles/11503834-building-custom-connectors-via-remote-mcp-servers)。 ## HTTPS 部署边界 PR MCP Builder 自动创建的范围包括批准的数据、分层搜索 DB、MCP 服务器执行文件、客户端设置和连接脚本。 机构 IT 人员需要根据操作环境准备以下项目。 - 公开或机构批准的域名和 DNS - TLS 证书和 HTTPS 反向代理 - OAuth、mTLS 或持有者令牌身份验证 - 服务器防火墙、审计日志、备份和机密信息管理 - ChatGPT/Claude 工作区连接器批准 使用远程 MCP 时，MCP 返回的批准法规内容可能会传输到外部 AI 服务。 仅对公开材料或已获得单独导出批准的材料使用，并优先使用本地 stdio 或批准的内部网络 MCP 处理机密法规。 ## 修订版更新方法 例如，输入同一个机构的 `人事法规1.hwp`、`人事法规2.hwp` 和 `人事法规3.hwp`，按照以下条件组织。 1. 文档中查找法规名称、制定/修订/全部修订历史。 2. 将具有相同机构和标准化法规名称的法规捆绑到一个法规系列中。 3. 根据修订日期、生效日期和内容哈希区分版本。 4. 使用最新的批准版本作为当前有效版本，并将以前的批准版本保存为修订历史。 5. 查询时，从机构 -> 法规 -> 目录/条款 -> 最新有效版本缩小范围。 如果正文历史记录缺失或日期冲突，则不会自动确定为审查对象。 ## 支持范围和限制 | 项目 | 当前范围 | | --- | --- | | 操作系统 | 优先支持 Windows 10/11 64 位版本 | | 输入 | PDF、HWP、HWPX、DOCX | | 结构 | 机构 -> 法规 -> 修订版 -> 目录/条款 -> 批准区块 | | 本地 UI | Streamlit，默认绑定到 `127.0.0.1` | | 搜索 | 分层浏览 + 最新有效版本过滤 + BM25/向量候选搜索 | | HWP 表格 | 默认提取，然后使用可选的 Kordoc CLI 增强，人工审查必要 | | 扫描 PDF | OCR 后端和韩语语言支持需要单独设置 | | 外部连接 | 需要批准的 HTTPS 部署或安全隧道 | ### 可选的 Kordoc 增强 增强 HWP 表格提取时，可以单独安装 [Kordoc 项目](https://github.com/chrisryugj/kordoc)。 PR MCP Builder 将 Kordoc 提取的单元格/列结构与基本解析器结果进行比较，并将匹配度足够的表格连接到审查候选人。 Kordoc 结果也不会自动批准，原始表格和人工对比。 - 该项目的作用：在 HWP 中增强表格单元格、列位置和合并结构 - 链接方法：用户单独安装的 Kordoc CLI 作为子进程调用 - 分发范围：PR MCP Builder 源代码和 Windows ZIP 不包含 Kordoc 源代码/执行文件 - 审查原则：在 Kordoc 表格匹配、升级和不匹配结果上留下审查标记，并在批准前对比原始文本 默认分发原则是不包含 Kordoc 源代码或执行文件。 Kordoc 是 Chris 公开的独立 MIT 项目。 使用前，请与此存储库的 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 一起查看 [Kordoc 许可证](https://github.com/chrisryugj/kordoc/blob/main/LICENSE)。 ## 安全原则 - 不将预处理本身视为安全控制。 - 检查、分类、人工批准、审计日志和未批准区块索引阻止是实际控制。 - 不将原始法规、运行时输出、API 密钥、令牌和用户本地路径提交到公共存储库。 - 在共享分发中，应用身份验证、机构租户隔离、访问控制和机构安全策略。 - 在公共分发之前，请查看 [SECURITY.md](SECURITY.md) 和 [公共存储库历史策略](docs/public_repository_history_policy_ko.md)。 ## 开发者验证和构建 ```powershell python -m unittest discover -s tests -v python -m build --sdist --wheel python scripts\audit_release_hygiene.py --workflow-scope available --include-untracked --include-source-path-scan ``` Windows 便携式 ZIP 文件是通过以下命令创建的。 ```powershell powershell -ExecutionPolicy Bypass -File scripts\build_windows_portable.ps1 -Version 0.1.0 ``` 结果文件位于 `dist\PR-MCP-Builder-Windows-x64-0.1.0.zip`。 请勿将 `data/`、`reports/`、`.tmp/`、`build/`、`dist/`、虚拟环境和实际机构文档提交到 Git。 有关详细设计和操作文档，请参阅 [docs](docs/)。源代码遵循 [MIT License](LICENSE)，外部组件条件在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中概述。