OFD-MCP

OFD 版式文件数据提取和生成 MCP（Model Context Protocol）服务。

功能特性

• ✅ 文本提取: 从 OFD 文件中提取文本内容
• ✅ 元数据提取: 获取文档标题、作者、创建日期等信息
• ✅ 按页提取: 支持按页面提取文本内容
• ✅ 页数统计: 获取 OFD 文件总页数
• ✅ 签章校验: 支持签名入口、签名值文件、References 摘要校验，兼容 SM3 摘要和 ASN.1 签名值识别
• ✅ 票据提取: 提取购买方、销售方、开票金额、开票明细、发票类型、开票日期等票据字段
• ✅ 文件生成: 创建符合 OFD 规范的版式文件

技术栈

• 运行时: Node.js >= 18
• 语言: TypeScript
• MCP SDK: @modelcontextprotocol/sdk
• XML 处理: xml2js
• ZIP 处理: adm-zip
• Schema 验证: zod

快速开始

1. 安装依赖

npm install

如需直接从 npm 使用 MCP 服务：

npx ofd-mcp

2. 构建项目

npm run build

默认构建会先编译 TypeScript，再混淆 dist/**/*.js。如需本地调试未混淆产物，可执行：

npm run build:plain

3. 配置 IDE

在支持 MCP 协议的 IDE 中添加服务器配置：

Cursor / VS Code (settings.json):

{
  "mcp.servers": [
    {
      "name": "ofd-mcp",
      "command": "node",
      "args": ["<path-to-project>/dist/index.js"],
      "cwd": "<path-to-project>"
    }
  ]
}

发布到 npm 后，也可以配置为：

{
  "mcp.servers": [
    {
      "name": "ofd-mcp",
      "command": "npx",
      "args": ["-y", "ofd-mcp"]
    }
  ]
}

npm 发布流程

发布前先执行本地检查：

npm run publish:check

确认无误后手动发布：

npm publish

发布脚本会在 prepublishOnly 阶段自动重新构建 dist/。

4. 使用工具

服务提供以下工具：

| 工具名称 | 功能 | |----------|------| | ofd_extract_text | 提取 OFD 文件中的文本内容 | | ofd_extract_metadata | 提取文档元数据 | | ofd_extract_pages_text | 按页提取文本内容 | | ofd_get_page_count | 获取 OFD 文件页数 | | ofd_verify_signature | 校验 OFD 签章摘要和签名值结构 | | ofd_extract_invoice | 提取票据版式 OFD 发票字段 | | ofd_create | 创建 OFD 版式文件 |

测试验证

import { OFDParser } from './src/parser/OFDParser.js';
import { OFDGenerator } from './src/generator/OFDGenerator.js';

// 生成 OFD 文件
const generator = new OFDGenerator();
await generator.generate('test.ofd', { title: '测试文档' }, [
  { textElements: [{ x: 100, y: 100, text: 'Hello OFD!' }] }
]);

// 解析 OFD 文件
const parser = new OFDParser();
const doc = await parser.parse('test.ofd');
console.log(parser.extractText(doc)); // Hello OFD!

项目结构

ofd-mcp/
├── src/
│   ├── types/ofd.ts          # OFD 数据类型定义
│   ├── parser/OFDParser.ts   # OFD 文件解析器
│   ├── signature/OFDSignatureVerifier.ts # OFD 签章校验服务
│   ├── invoice/OFDInvoiceExtractor.ts # 票据字段提取服务
│   ├── generator/OFDGenerator.ts # OFD 文件生成器
│   ├── mcp/server.ts         # MCP 服务实现
│   └── index.ts              # 服务入口文件
├── DEVELOPMENT.md            # 开发文档
├── DEPLOYMENT.md             # 部署文档
├── OFD版式文件规范.docx       # OFD 规范文档
└── package.json

规范符合

基于 GB/T 33190-2016《电子文件存储与交换格式 版式文档》标准开发，支持 OFD 1.0 版本。

文档

• 开发文档 - 详细的技术实现说明
• 部署文档 - 部署和配置指南

许可证

MIT