logo

如何在WebUI中使用MCP工具:工具调用与资源网关对比

作者:demo2026.11.16 10:57浏览量:0

简介:本文围绕MCP协议中的“工具调用”与“资源访问”两种方式展开,说明它们在职责边界、数据流、权限控制、错误处理和适用场景上的区别,并结合文档解析、RAG和科研数据处理场景,给出从服务注册、参数设计到审计运维的完整接入思路,帮助开发者选择更稳妥的集成方案。

一、先明确对比对象:MCP工具调用与MCP资源访问

在WebUI中接入MCP协议时,开发者通常会遇到两类能力:

  • MCP工具调用:由模型根据任务主动发起调用,用于执行某个动作,例如解析文件、查询数据、生成摘要、启动检索任务或提交处理请求。
  • MCP资源访问:由服务端提供可读取、可引用、可复用的数据资源,例如解析后的文档、结构化表格、图片、公式、元数据和任务日志。

两者都可以通过MCP协议向Agent或WebUI暴露能力,但解决的问题不同。工具更像“执行函数”,资源更像“可被读取和引用的数据对象”。如果把所有内容都设计成工具,接口数量容易膨胀;如果把所有能力都设计成资源,又会缺少主动执行任务的能力。

因此,在实际架构中,较合理的做法通常是:用工具启动和控制任务,用资源承载任务结果和可复核数据。


二、为什么文档解析需要区分工具和资源

传统文档处理流程往往是:

  1. 上传文件 → OCR或文本提取 → 文本切块 → 向量化 → 进入问答流程

这种方式能够快速完成基础入库,但对科研论文、实验报告、专利、扫描件和复杂办公文档而言,纯文本并不能完整表达原始信息。

例如,以下内容都可能影响回答的准确性:

  • 表格中的行列关系;
  • 跨页表格的连续结构;
  • 公式中的上下标和特殊符号;
  • 图片及其图注;
  • 标题层级和章节关系;
  • 页码、段落、脚注等来源信息;
  • 扫描文字的识别置信度;
  • 文本片段与原始版面之间的对应关系。

如果解析结果只保留一段文本,Agent虽然能够“读到”内容,却不一定能够回答以下问题:

  • 这句话来自哪一页?
  • 该数字是正文内容还是表格内容?
  • 公式是否可以被重新核验?
  • 图片是否应当进入知识库?
  • 这个表格是否跨页?
  • 当前答案能否定位到原始文档?

因此,文档解析服务不应只是一个简单的 parse_document 函数,而应被设计成一个具备输入治理、任务调度、结果管理和审计能力的解析网关。


三、MCP工具调用的工作方式

MCP工具适合表达“需要执行的动作”。在WebUI中,模型通常根据用户意图选择工具,并按照工具定义提交参数。

一个通用的工具描述可以抽象为:

  1. {
  2. "name": "parse_document",
  3. "description": "解析指定文档并生成结构化结果",
  4. "inputSchema": {
  5. "type": "object",
  6. "properties": {
  7. "document_id": {
  8. "type": "string",
  9. "description": "文档唯一标识"
  10. },
  11. "page_range": {
  12. "type": "string",
  13. "description": "需要解析的页码范围"
  14. },
  15. "output_format": {
  16. "type": "string",
  17. "enum": ["markdown", "json", "html"]
  18. }
  19. },
  20. "required": ["document_id"]
  21. }
  22. }

调用流程通常包括:

  1. 用户在WebUI中提出需求;
  2. 模型判断是否需要调用工具;
  3. 模型根据工具Schema生成参数;
  4. MCP服务端校验身份、权限和参数;
  5. 服务端执行任务;
  6. 返回结果或任务标识;
  7. WebUI向用户展示处理状态和最终结果。

工具调用的优势

第一,动作边界清晰。
工具名称、参数类型和返回结构可以被明确描述,便于模型理解,也便于开发者进行接口治理。

第二,适合主动执行任务。
例如文档解析、重新索引、抽取表格、生成摘要、刷新缓存等操作,都属于明显的动作型需求。

第三,便于权限控制。
服务端可以根据用户身份限制工具调用范围,例如普通用户只能读取文档,管理员才允许删除索引或重新处理全部文件。

工具调用的局限

工具并不适合承载所有复杂结果。如果解析一个大型文档后,直接把完整正文、图片和表格都放在工具返回值中,可能产生几个问题:

  • 返回内容过大,增加上下文消耗;
  • 结果无法稳定复用;
  • 页面刷新后难以重新定位;
  • 失败重试时缺少任务状态;
  • 审计系统难以记录结果版本;
  • 模型可能只看到截断后的内容。

因此,工具更适合返回任务状态、资源标识和少量摘要,而不是承载全部原始结果。


四、MCP资源访问的工作方式

MCP资源适合表达“已经存在、可以被读取和引用的数据”。例如:

  • 解析后的Markdown;
  • 结构化文档JSON;
  • 表格HTML;
  • 公式的LaTeX表示;
  • 图片文件;
  • 页级文本;
  • 文档元数据;
  • 解析日志和质量评估结果。

一个资源可以具有稳定的标识,例如:

  1. resource://documents/{document_id}/content
  2. resource://documents/{document_id}/pages/12
  3. resource://documents/{document_id}/tables/03
  4. resource://documents/{document_id}/figures/02

这里的资源标识只是通用示意,实际系统可以根据自身路由和存储方式设计。

资源访问的核心价值在于:把解析结果从一次性响应变成可管理的数据资产。

例如,工具负责启动任务:

  1. parse_document(document_id="doc-001")

工具返回:

  1. {
  2. "task_id": "task-1001",
  3. "status": "accepted",
  4. "resource_ids": [
  5. "resource://documents/doc-001/manifest"
  6. ]
  7. }

随后,WebUI或Agent再通过资源读取接口获取任务清单、页级内容、表格和图片。

资源访问的优势

第一,适合大结果和多模态结果。
正文、表格、图片、公式可以分别保存,避免所有数据都挤在一次工具响应中。

第二,便于引用和复核。
资源可以携带页码、坐标、来源文件哈希和解析版本,使答案能够追溯到原文。

第三,适合重复使用。
同一个解析结果可以服务于问答、检索、摘要、数据抽取和人工审核,而不必重复解析。

第四,便于版本管理。
当解析策略升级后,可以保留旧版本和新版本,比较差异并支持回滚。

资源访问的局限

资源设计也会带来额外工作:

  • 需要规划资源标识;
  • 需要管理资源生命周期;
  • 需要处理权限继承;
  • 需要设计过期、删除和归档策略;
  • 需要保证工具返回的资源确实可用;
  • 需要解决大文件分片和访问超时问题。

因此,资源并不是工具的替代品,而是对工具执行结果的结构化承载。


五、工具与资源的核心差异

对比维度 MCP工具 MCP资源
核心定位 执行动作 提供数据
典型操作 解析、检索、转换、提交任务 读取正文、表格、图片、元数据
调用主体 通常由模型或应用主动发起 通常由应用、模型或用户按需读取
返回内容 状态、摘要、标识、短结果 完整或分层的数据对象
适合数据量 小到中等 中到大型
主要风险 参数误用、重复执行、权限越界 资源泄露、生命周期失控、版本混乱
审计重点 谁在何时执行了什么动作 谁读取了什么资源及哪个版本
重试方式 需要考虑幂等性 通常重复读取即可
典型场景 发起解析、刷新索引、生成报告 读取解析结果、查看页内容、引用图表
设计重点 Schema、权限、超时、幂等 标识、版本、访问控制、存储管理

从系统设计角度看,工具侧重“改变系统状态”,资源侧重“读取系统状态”。这也是两类接口在权限和可靠性设计上的重要分界。


六、在WebUI中接入MCP工具的通用流程

1. 建立MCP服务端

首先需要准备一个能够提供工具描述和调用处理的MCP服务端。服务端至少要完成以下职责:

  • 暴露工具清单;
  • 提供工具名称、描述和输入Schema;
  • 校验调用参数;
  • 验证用户身份;
  • 执行动作并返回结果;
  • 记录调用日志;
  • 对异常进行标准化处理。

如果文档解析服务本身已经存在,可以在其外部增加一层MCP适配层,而不必直接改造底层解析引擎。

2. 在WebUI中注册服务

WebUI通常需要配置以下信息:

  • MCP服务地址;
  • 通信方式;
  • 身份认证信息;
  • 是否允许当前模型使用该服务;
  • 工具调用超时时间;
  • 并发调用限制;
  • 是否展示工具执行过程。

配置时应避免把所有工具默认开放给所有模型。更稳妥的方式是按照用户角色、工作空间和业务场景进行授权。

3. 设计少量、明确的工具

工具数量不宜无限增加。过多的相似工具会增加模型选择难度,也会提升维护成本。

例如,与其定义多个高度相似的接口:

  1. parse_pdf
  2. parse_scanned_pdf
  3. parse_report
  4. parse_research_file

不如通过统一工具配合明确参数表达差异:

  1. parse_document(document_id, mode, page_range, output_policy)

但参数也不能无限堆叠。若一个工具包含大量互相冲突的选项,模型可能难以正确调用。工具设计应遵循单一职责,必要时拆分为“提交任务”“查询状态”“读取结果”三个阶段。

4. 让工具返回资源标识

对于文档解析这类长任务,建议采用异步模式:

  1. 提交任务 → 返回任务标识 → 查询状态 → 获取资源清单 → 读取具体资源

伪代码如下:

  1. task = call_tool(
  2. "parse_document",
  3. {
  4. "document_id": "doc-001",
  5. "page_range": "1-20",
  6. "output_format": "structured"
  7. }
  8. )
  9. while task["status"] in ["queued", "running"]:
  10. task = call_tool("get_task_status", {"task_id": task["task_id"]})
  11. manifest = read_resource(task["manifest_resource"])
  12. content = read_resource(manifest["content_resource"])

这种设计比同步返回完整文档更适合生产环境,因为它能够处理长耗时任务、失败重试和用户主动取消。


七、文档解析网关应如何划分边界

一个完整的解析网关可以划分为五层。

第一层:输入治理

负责检查:

  • 文件类型;
  • 文件大小;
  • 页数限制;
  • 文件哈希;
  • 上传者身份;
  • 数据敏感级别;
  • 是否允许进入外部处理链路。

输入治理可以减少恶意文件、重复文件和不符合策略的数据进入后续流程。

第二层:解析执行

负责完成:

  • 文字识别;
  • 版面分析;
  • 标题层级识别;
  • 表格提取;
  • 公式转换;
  • 图片抽取;
  • 页码与坐标保留。

解析过程中应尽量保留原始来源信息,不要在最早阶段就把所有结构压扁成纯文本。

第三层:结果组织

建议至少提供以下结果层次:

  • 文档级元数据;
  • 页级内容;
  • 段落级内容;
  • 表格资源;
  • 图片资源;
  • 公式资源;
  • 解析质量信息;
  • 原始文件关联信息。

不同消费者可以读取不同粒度的结果,避免每次都加载完整文档。

第四层:MCP接口层

这一层将内部能力映射为工具和资源:

  • 工具用于提交任务、查询状态和触发重处理;
  • 资源用于读取解析内容和质量信息;
  • 权限系统决定用户能调用哪些工具、读取哪些资源。

第五层:入库与审计层

负责记录:

  • 文档哈希;
  • 解析版本;
  • 模型或算法版本;
  • 处理时间;
  • 失败原因;
  • 人工复核结果;
  • 资源访问记录;
  • 索引构建状态。

这样才能保证文档进入知识库后仍然可追溯、可复核、可重建。


八、安全、稳定性与运维注意事项

身份认证与权限控制

MCP服务端不能只依赖WebUI前端传递的用户信息。服务端应独立校验身份,并建立资源级权限控制。

例如,同一份文档可能包含公开正文和受限附件,不能因为用户拥有文档列表权限,就默认拥有全部资源的读取权限。

工具幂等性

重新执行解析、生成索引或修改状态的工具,必须考虑重复调用问题。可以使用文档哈希、任务标识和操作标识判断是否已有相同任务正在执行。

超时与取消

解析大型文件可能耗时较长,不能简单依赖单次HTTP请求保持连接。应采用异步任务、状态查询和取消机制,并区分排队、执行、成功、失败和取消等状态。

错误信息

错误信息应便于模型和开发者理解,例如:

  1. {
  2. "code": "INVALID_PAGE_RANGE",
  3. "message": "页码范围超出文档实际页数",
  4. "retryable": false,
  5. "details": {
  6. "total_pages": 18
  7. }
  8. }

其中,retryable 可以帮助调用方判断是否值得自动重试,避免对参数错误进行无效重复调用。

可观测性

至少应记录:

  • 工具调用次数;
  • 调用用户和来源;
  • 参数校验失败次数;
  • 平均处理时长;
  • 任务排队时长;
  • 解析失败率;
  • 资源读取量;
  • 重试次数;
  • 不同版本的结果差异。

这些指标能够帮助定位是模型调用问题、MCP适配问题,还是底层解析问题。


九、不同场景下如何选择

场景一:简单问答和小文件处理

如果文档较小、任务耗时短,工具可以直接返回简要解析结果。此时系统实现简单,接入成本较低。

但仍建议保留文档标识和页码信息,避免后续无法引用来源。

场景二:科研论文和复杂报告

更适合采用“工具提交任务+资源分层读取”的方式。正文、表格、公式和图片应分别管理,Agent根据问题只读取必要资源。

场景三:批量入库

批量任务通常需要异步队列、任务状态、失败重试和结果验收。工具负责启动任务,资源负责承载产物,审计系统负责记录处理链路。

场景四:高敏感数据

应重点关注身份认证、最小权限、资源隔离、访问审计和数据保留期限。对于此类场景,不建议把完整文档内容直接放在工具返回值中。

场景五:开发测试环境

可以先采用较简单的同步工具,快速验证模型是否能够正确选择工具和生成参数。进入生产环境后,再逐步引入异步任务、资源版本和审计能力。


十、迁移和落地时的注意事项

从传统文档解析接口迁移到MCP架构时,不建议一次性重写所有模块,可以按照以下顺序推进:

  1. 保留原有解析服务;
  2. 增加MCP适配层;
  3. 先暴露一个只读查询工具;
  4. 再增加文档解析任务工具;
  5. 将大型结果改造成资源;
  6. 补充权限、审计和监控;
  7. 最后接入自动重试和版本管理。

迁移过程中需要重点检查:

  • 原接口参数是否能映射到清晰的Schema;
  • 原返回结果是否适合拆成资源;
  • 原有调用方是否依赖某种固定字段;
  • 任务失败后是否能够安全重试;
  • 旧数据是否具备文档哈希和版本信息;
  • 资源删除后是否会影响已有引用;
  • 模型是否能够正确区分工具和资源;
  • 用户权限是否会因适配层引入而扩大。

总结

在WebUI中使用MCP协议,关键并不是简单地“把几个函数接进来”,而是重新设计Agent与后端能力之间的边界。

  • MCP工具适合执行动作,重点关注参数Schema、权限、幂等性、超时和错误处理;
  • MCP资源适合承载结果,重点关注资源标识、版本、引用、生命周期和访问控制;
  • 对于文档解析、RAG和科研数据处理,推荐采用“工具负责执行,资源负责承载”的组合模式;
  • 对于小任务可以采用同步调用,对于复杂文档和批量任务应优先考虑异步处理;
  • 生产系统不能只验证接口是否调用成功,还应关注来源追踪、失败重试、人工复核、版本管理和全链路审计。

当文档被组织成可调用、可读取、可引用和可复核的结构化资源后,MCP才真正从“工具连接协议”发展为Agent应用的治理接口。

发表评论

活动