利用MCP协议与AI助手生成波兰法律文书：开源项目实战指南

1. 项目概述：当AI助手学会起草波兰法律文书

如果你是一位在波兰工作或生活的开发者、创业者，或者你的业务涉及波兰市场，那么你一定对处理当地的法律文书感到头疼。无论是租房、买卖二手车、还是和朋友之间写个借款协议，一份符合波兰法律规范的正式文件往往意味着要花钱找律师，或者花大量时间在网络上寻找不靠谱的模板。现在，情况正在改变。通过一个名为PismoSzyteNaMiare MCP Server的开源项目，你可以让Claude、Cursor这类AI助手，直接为你生成专业、合规的波兰法律文件PDF。

这个项目的核心，是将波兰知名的在线法律文书生成服务PismoSzyteNaMiare.pl，无缝集成到支持Model Context Protocol (MCP)的AI工作流中。MCP是Anthropic为Claude推出的一种协议，它允许AI模型安全、可控地调用外部工具和数据。简单来说，这个MCP服务器就像一个“翻译官”和“接线员”，它让AI助手理解了如何与PismoSzyteNaMiare的API对话，从而把“帮我写一份车辆买卖合同”这样的自然语言指令，转换成API调用，并最终将一份格式精美的PDF文档交到你手上。

最吸引人的一点是，它完全免费，且无需API密钥。这背后是SoftVoyagers开发者社区的贡献，他们将PismoSzyteNaMiare的公共服务封装成了标准的MCP工具，极大降低了使用门槛。无论你是想快速生成一份《umowa kupna-sprzedaży》（买卖合同），还是起草一份《pełnomocnictwo》（授权委托书），现在都可以在你的代码编辑器或AI聊天窗口中直接完成。

2. 核心原理与架构拆解：MCP如何桥接AI与法律API

要理解这个项目的价值，我们需要先拆解它的技术架构。这并非一个功能复杂的独立应用，而是一个设计精巧的“适配器”。它的核心任务非常明确：遵循MCP协议规范，将AI助手的请求转发给PismoSzyteNaMiare的REST API，并将API的响应（通常是PDF文件或文档预览）以MCP规定的格式返回给AI助手。

2.1 Model Context Protocol (MCP) 的角色

MCP是这一切得以实现的基础。你可以把它想象成AI世界的“USB协议”。在没有MCP之前，每个AI应用（如Claude Desktop）想要连接外部工具（如日历、数据库、API），都需要开发者为其编写特定的插件，耦合度高，且难以复用。MCP定义了一套标准的通信方式（包括stdio和HTTP），以及工具描述、调用、资源管理的格式。这意味着，只要一个工具（如本MCP服务器）实现了MCP服务端接口，任何兼容MCP的客户端（如Claude Desktop、Cursor）都能立即识别并使用它，无需额外适配。

本项目中，MCP服务器主要暴露了三个标准化的“工具”（Tools）：

1. list_document_types: 列出所有支持的文档类型及其所需字段。这相当于AI助手的“菜单”，让它知道能生成什么，以及每种文档需要哪些信息（如买卖双方姓名、资产描述、价格等）。
2. get_document_preview: 根据输入数据生成文档的HTML预览。这是一个非常实用的“草稿”功能，允许用户在生成最终PDF前，先确认内容格式是否正确。
3. generate_document: 核心工具，接收结构化数据，调用后端API，最终返回一个PDF文件的Base64编码或可访问的URL。

2.2 服务器作为无状态代理

项目的架构极其简洁，是一个典型的“瘦客户端”或“无状态代理”。它本身不处理任何业务逻辑，也不存储任何用户数据。所有与文档生成相关的复杂工作——法律条款的组装、变量填充、PDF渲染——全部由远端的https://pismoszytenamiare.pl服务完成。

这种设计带来了多重好处：

• 安全性：用户的敏感数据（如个人信息、合同条款）直接发送至受信任的、专业的法律服务平台，而非经过第三方中转，降低了数据泄露风险。MCP服务器只负责协议转换，不触碰数据内容。
• 可维护性：当PismoSzyteNaMiare的主服务更新文档模板或修复法律条款时，所有通过MCP服务器生成的文档会自动同步更新，无需修改MCP服务器代码。
• 轻量化：MCP服务器的代码库可以保持非常精简，只专注于实现MCP协议和HTTP客户端功能，部署和运行成本极低。

2.3 双传输模式：Stdio与HTTP

为了适应不同的使用场景，项目提供了两种连接方式，这也是MCP协议的标准支持。

• Stdio (标准输入/输出)：这是为Claude Desktop等本地桌面应用设计的。配置后，Claude Desktop会作为一个父进程，启动这个MCP服务器（通过npx命令），两者通过进程间的标准输入输出流进行通信。这种方式完全在本地运行，延迟低，隐私性好，适合个人日常使用。

  // Claude Desktop 配置示例 { "mcpServers": { "pismoszytenamiare": { "command": "npx", "args": ["pismoszytenamiare-mcp"] } } }

• HTTP (远程服务器)：项目在Azure上部署了一个公开可用的HTTP端点 (https://softvoyagers-pismoszytenamiare-mcp.azurewebsites.net/mcp)。这种方式是为了支持Claude.ai网页版、Glama等MCP连接管理器，以及其他任何可以通过网络访问MCP服务的客户端。用户无需在本地安装Node.js或运行任何命令，只需提供该URL即可连接。这大大扩展了工具的可用性，让没有技术背景的用户也能通过网页版Claude使用该功能。

注意：使用公共HTTP端点时，虽然数据最终仍直达PismoSzyteNaMiare，但你的请求会经过Azure服务器中转。对于包含高度敏感信息的法律文件，从隐私角度考虑，更推荐使用本地Stdio模式。公共端点更适合快速体验和非敏感文档的生成。

3. 从零开始：配置与接入全指南

了解了原理，接下来我们进入实战环节。我将以最常见的Claude Desktop和Cursor编辑器为例，手把手带你完成配置。整个过程大约只需要5分钟。

3.1 环境准备与前置检查

在开始之前，请确保你的系统满足以下条件：

1. Node.js环境：由于本地Stdio模式需要通过npx运行包，你的电脑上需要安装Node.js (版本14或以上)。打开终端，输入node --version检查。如果没有，请前往Node.js官网下载安装。
2. Claude Desktop：从Anthropic官网下载并安装最新版的Claude Desktop应用。
3. 网络连接：能够正常访问https://pismoszytenamiare.pl和https://registry.npmjs.org（用于下载npm包）。虽然项目本身免费，但生成文档需要调用在线的API服务。

3.2 配置Claude Desktop (macOS)

Claude Desktop的配置文件位于一个固定的用户目录下。以下是详细步骤：

1. 定位配置文件： 打开macOS的“访达”（Finder）。按下Cmd+Shift+G快捷键，弹出“前往文件夹”对话框。输入路径~/Library/Application Support/Claude/并回车。这个目录通常存放着Claude Desktop的应用数据。

2. 编辑配置文件： 在该目录下，找到名为claude_desktop_config.json的文件。如果首次配置，这个文件可能不存在，你需要手动创建它。

   • 使用你喜欢的文本编辑器（如VS Code、Sublime Text甚至TextEdit）打开或创建这个文件。
   • 将以下配置内容复制进去。关键点：args数组里的pismoszytenamiare-mcp就是我们要调用的npm包名。

   { "mcpServers": { "pismoszytenamiare": { "command": "npx", "args": ["pismoszytenamiare-mcp"] } } }

3. 保存并重启： 保存claude_desktop_config.json文件。完全退出Claude Desktop 应用（不仅仅是关闭窗口，最好从菜单栏退出或通过Cmd+Q），然后重新启动它。

4. 验证连接： 重启后，在Claude Desktop中新建一个对话。如果配置成功，你通常会在输入框上方或侧边栏看到一个新工具的图标或提示。更直接的方式是，你可以尝试输入：“你能用PismoSzyteNaMiare帮我生成哪些文档？” 如果Claude正确识别了MCP服务器，它会调用list_document_types工具，并给你一个清晰的列表。

实操心得：在macOS上，~/Library/是隐藏文件夹。通过Cmd+Shift+G是访问它的最快方式。另外，修改配置文件后，必须彻底重启Claude Desktop，仅仅刷新页面是无效的。如果重启后工具仍未出现，可以检查Claude Desktop的日志（通常可以在应用内设置中找到或通过控制台查看），看是否有关于MCP服务器启动失败的报错信息。

3.3 配置Cursor编辑器

Cursor是另一款深度集成AI的代码编辑器，它也支持MCP。配置过程与Claude Desktop类似，但配置文件的位置和结构稍有不同。

1. 定位配置文件： Cursor的MCP配置通常在其设置文件中。打开Cursor，进入设置（Settings）。在设置界面，寻找“Advanced”或“MCP Servers”相关选项。更直接的方式是，配置文件通常位于：

   • macOS:~/Library/Application Support/Cursor/User/globalStorage/mcp.json
   • Windows:%APPDATA%\Cursor\User\globalStorage\mcp.json
   • Linux:~/.config/Cursor/User/globalStorage/mcp.json

2. 编辑配置文件： 打开或创建mcp.json文件。Cursor的MCP配置通常是一个MCP服务器数组。添加如下配置：

   { "mcpServers": [ { "name": "pismoszytenamiare", "command": "npx", "args": ["pismoszytenamiare-mcp"] } ] }

3. 保存并重启： 保存文件，并重启Cursor编辑器。重启后，你可以在Cursor的AI聊天界面中测试，询问AI关于生成波兰法律文档的能力。

3.4 使用HTTP端点连接（适用于Claude.ai等）

对于无法直接运行本地命令的环境，如网页版Claude.ai，或者你希望在任何地方通过统一的接口调用，可以使用项目提供的公共HTTP端点。

1. 获取连接信息： 你需要的唯一信息就是端点URL：https://softvoyagers-pismoszytenamiare-mcp.azurewebsites.net/mcp

2. 在支持MCP的客户端中配置： 以Glama(一个流行的MCP连接管理平台) 为例：

   • 登录Glama，添加一个新的MCP服务器。
   • 选择传输类型为 “HTTP”。
   • 在服务器URL字段中，填入上述端点地址。
   • 保存后，Glama会帮你管理这个连接，并可以将其提供给Claude.ai等客户端使用。

   如果你使用的客户端直接支持输入HTTP MCP服务器地址，只需在相应设置项中粘贴该URL即可。

3. 直接使用： 配置完成后，在AI对话中你就可以像使用本地工具一样，发出生成文档的指令了。

4. 实战演练：生成你的第一份法律文件

配置成功后，让我们通过一个完整的例子，看看如何与AI协作，生成一份专业的《Umowa kupna-sprzedaży samochodu》（汽车买卖合同）。假设场景是：我想把我的2018款大众高尔夫，以45,000 PLN的价格卖给Jan Kowalski。

第一步：探索可用工具你可以直接问AI：“请列出PismoSzyteNaMiare支持的所有文档类型。” AI会调用list_document_types工具，返回一个结构化的列表，其中包含每种文档的标识符（如sales_contract）和所需字段的详细说明。

第二步：构思文档内容并收集信息根据AI提供的字段说明，你需要准备以下核心信息：

• 文档类型:sales_contract(买卖合同)
• 子类型:vehicle(车辆)
• 合同双方信息: 卖家（你）和买家（Jan Kowalski）的姓名、地址、PESEL（波兰身份证号）或NIP（税号）。
• 标的物描述: 车辆品牌（Volkswagen）、型号（Golf）、年份（2018）、VIN码、车牌号、里程数等。
• 交易条款: 价格（45,000 PLN）、付款方式（银行转账）、交付日期和地点。
• 其他条款: 是否包含保修、违约责任等（可选）。

第三步：通过自然语言指令生成现在，你可以用一段话描述你的需求，AI会帮你结构化数据并调用工具：

“请帮我生成一份汽车买卖合同。我是卖家，Anna Nowak，住在华沙，PESEL是12345678901。买家是Jan Kowalski，PESEL是98765432109。车辆是2018年的大众高尔夫，VIN码是WVWZZZ1KZ8P123456，目前里程8万公里。售价是45,000兹罗提，计划在下周五在华沙我的住处交付，付款方式为银行转账。请包含标准的车辆状况描述条款。”

AI在理解你的请求后，会先调用get_document_preview工具，生成一个HTML预览链接返回给你。你可以点击链接检查所有信息是否填写正确，特别是人名、数字和日期。

第四步：生成最终PDF确认预览无误后，你可以告诉AI：“预览看起来没问题，请生成最终的PDF文档。” AI随后会调用generate_document工具。几秒钟后，它会返回一个PDF文件的下载链接或直接以Base64格式提供文件。你点击链接即可下载一份格式规范、条款完整的波兰语买卖合同PDF，可以直接打印签署。

整个交互过程的核心优势在于：你无需知道每个字段的具体API参数名，也无需手动拼接JSON数据。你只需要用自然语言描述你的业务场景，AI负责理解、结构化并调用正确的工具。这极大地简化了流程，尤其适合处理非标准或复杂的合同条款。

5. 支持的文档类型深度解析与使用场景

PismoSzyteNaMiare MCP服务器支持生成多种常见的波兰法律文书，每种都有其特定的使用场景和定制选项。理解这些文档的细节，能帮助你在与AI交互时更准确地表达需求。

5.1 Umowa kupna-sprzedaży (买卖合同)

这是使用最频繁的文档之一。它不仅仅是一个通用模板，而是根据标的物类型进行了细分：

• 车辆买卖：除了双方信息，需要详细填写车辆识别号（VIN）、品牌型号、生产年份、发动机排量、里程数、车牌号等。合同会自动包含关于车辆法律状态（无抵押、无违章）的声明条款。
• 不动产买卖：涉及房产地址、土地登记号（numer księgi wieczystej）、面积、产权情况等更复杂的信息。对于大额交易，强烈建议在生成后由专业律师复核。
• 动产/其他物品买卖：适用于家具、电子产品、艺术品等。需要清晰描述物品名称、规格、序列号（如有）和现状。

注意事项：在波兰，私人间的车辆买卖，签署这份合同是所有权转移的必要步骤之一。生成合同后，买卖双方需共同前往交通局（Wydział Komunikacji）办理过户手续。合同中填写的VIN码和发动机号必须与车辆行驶证（dowód rejestracyjny）完全一致。

5.2 Pełnomocnictwo (授权委托书)

当你需要委托他人代为处理某些事务（如去银行办理业务、接收信件、处理房产事宜）时，就需要这份文件。通过MCP生成时，你需要明确：

• 委托范围：是特别授权（pełnomocnictwo szczególne，针对具体事项）还是普通授权（pełnomocnictwo ogólne，范围较广）？AI工具通常会提供选项或让你用文字描述范围。
• 权限细节：例如，委托银行事务时，是否需要授权存取款、申请贷款？描述越具体，生成的委托书越能保护你的权益。
• 有效期：可以设定具体的终止日期，或约定在完成特定事务后自动失效。

5.3 Wypowiedzenie umowy (合同解约函)

无论是解租公寓、取消健身房会员卡还是终止网络服务合同，一份书面解约函通常是法律要求的。生成时需注意：

• 合同信息：提供原合同的编号、签署日期等标识信息。
• 解约依据：引用合同中的解约条款（例如，提前一个月书面通知）。
• 解约生效日期：明确说明你希望合同在哪一天终止。根据波兰《民法典》，许多服务合同（如租房）的解约通知期是固定的，务必遵守。
• 交付方式：生成PDF后，建议通过挂号信（list polecony）寄送给对方，并保留邮寄凭证，这在发生纠纷时是关键证据。

5.4 Umowa pożyczki (借款协议)

即使是朋友或家人间的借款，一份简单的协议也能避免未来的误会。生成借款协议时，需要厘清：

• 金额与币种：明确借款总额（例如：10,000 PLN）。
• 利息：约定年利率或月利率。根据波兰法律，若无约定，则视为无息借款。但即使是无息，也建议在协议中写明“零利率”（oprocentowanie 0%），以示明确。
• 还款计划：是一次性偿还还是分期？每期还款金额和日期是什么？
• 担保：是否有抵押物或担保人？虽然简单协议可能不包含，但如果有，应在条款中注明。

5.5 Protokół zdawczo-odbiorczy (交接验收记录)

在租房退租、项目交付、设备归还时，这份记录至关重要。它用于确认物品的数量、状态和已完成的交接。生成时应详细列出：

• 交接物品清单：对于退租，应包括房间内所有固定设施和房东提供的家具家电，并逐一记录其现状（如：冰箱-运行正常，但门上有划痕；墙面-卧室东墙有约5cm裂缝）。
• 仪表读数：水电燃气表的当前读数。
• 钥匙交付：记录交付的钥匙数量和类型。
• 双方声明：记录交接时双方无其他异议的声明。双方签字后，各执一份，可有效避免押金纠纷。

6. 高级技巧与最佳实践

掌握了基本用法后，以下一些技巧能让你更高效、更安全地使用这个工具。

6.1 利用预览功能进行迭代修改

不要试图在一次指令中就生成完美的最终版。get_document_preview工具是你的“草稿纸”。它的工作流程应该是：

1. 首次生成预览，检查整体结构和必填信息。
2. 发现错误或遗漏（例如地址写错、日期格式不对），直接告诉AI：“预览中买家的出生日期错了，应该是1990年5月15日。另外，请在付款条款里加上‘应在交付当日付清’。”
3. AI会基于你的反馈，调整输入数据，再次调用预览工具。你可以反复这个过程，直到对草稿完全满意。
4. 最后再生成PDF。这比生成PDF后发现错误再重新来过要高效得多。

6.2 处理复杂与自定义条款

标准模板覆盖了常见情况，但现实中的合同往往需要特殊约定。你可以通过自然语言指示AI添加自定义条款：

• 示例指令：“在合同的‘其他条款’部分，加上一条：‘卖方保证该车辆在交付后三个月内，发动机和变速箱无重大故障，否则买方有权要求修理或协商降价。’”
• 操作原理：AI会将你的这段描述文本，作为一个自定义字段（如additional_clauses）的值，传递给API。API会将其插入到文档模板的适当位置。生成预览后，务必仔细检查这些自定义条款的表述是否准确、无歧义。

6.3 数据安全与隐私考量

虽然项目设计为无状态代理，且数据直达PismoSzyteNaMiare，但仍有几点需要注意：

1. 传输安全：无论是Stdio本地通信还是HTTP远程调用，确保你使用的AI客户端（如Claude Desktop）与MCP服务器之间的连接是可信的。使用公共Wi-Fi时需谨慎。
2. 信息最小化：只提供生成文档所必需的信息。例如，在简单的借款协议中，可能不需要提供详细的家庭住址。
3. PDF处理：生成的PDF文件可能缓存在AI助手的对话历史中。对于包含敏感信息的合同，在下载后，可以考虑在AI对话中删除包含文件链接或内容的消息。
4. 本地部署（高级选项）：对于有极高安全要求的企业用户，理论上可以克隆该MCP服务器的开源代码，在自己的服务器上部署一个私有实例。但这需要你具备基本的Node.js服务器运维能力。

6.4 与AI工作流深度结合

你可以将文档生成嵌入到更大的自动化流程中：

• 在Cursor中编写商业计划书：当写到“合作伙伴协议”部分时，直接让AI根据上下文提取双方公司名、责任等关键信息，调用MCP工具生成协议草案。
• 处理客户咨询：如果你开发了一个客服聊天机器人，当识别到用户需要“解约”意图时，可以自动引导用户填写必要信息，后台通过MCP服务器生成解约函，并提供下载。
• 批量生成：虽然当前工具主要面向单次交互，但你可以通过编写脚本，循环调用MCP服务器的HTTP端点（如果公开端点支持或你自建了服务），结合不同的数据源，实现文档的批量生成。

7. 常见问题排查与故障排除

在实际使用中，你可能会遇到一些问题。以下是一些常见情况的排查思路。

一个典型的调试流程：当工具调用失败时，首先在终端（对于Stdio模式）或浏览器的开发者工具网络面板（对于HTTP模式）中查看错误日志。错误信息通常会指出是网络问题、认证问题还是参数错误。然后，简化你的请求到最基础的形式（例如，只生成一个最简单的文档），测试基本功能是否正常，再逐步添加复杂参数。

8. 项目生态与未来展望

PismoSzyteNaMiare MCP Server并非孤立存在，它是SoftVoyagers免费API生态中的一员。这个社区致力于将各种实用的公共服务封装成易于开发者集成的API或协议接口。了解这个生态，能帮助你发现更多提高效率的工具。

除了法律文书生成，你还可以探索：

• LinkMeta：获取任何网页链接的元数据（标题、描述、图片），非常适合构建内容聚合或预览功能。
• PDFSpark：简单的PDF处理API。
• OGForge：动态生成Open Graph图片，用于社交媒体分享。
• Faktuj：波兰语的发票相关服务（如其名，“开发票”）。

从技术趋势来看，MCP协议正在成为AI助手扩展其能力的标准方式。未来，我们可能会看到：

1. 更多本地化服务集成：类似的项目可能会出现在其他国家，将本地的政务、法律、商业文档生成服务接入AI。
2. 更复杂的交互模式：目前的工具主要是“一问一答”式的生成。未来可能出现支持多轮谈判、条款对比、风险提示的更智能的“法律助手”MCP服务。
3. 与企业工作流集成：MCP服务器可以部署在企业内网，连接内部的合同管理系统、客户数据库，实现从客户信息到标准合同草案的自动填充和生成。

最后一点个人体会：这个项目完美地诠释了“好的工具让人察觉不到其存在”的理念。它没有试图创造一个全新的、复杂的法律AI，而是巧妙地用MCP这个“插头”，将成熟的、专业的PismoSzyteNaMiare服务接入了我们日益熟悉的AI助手环境中。对于在波兰的开发者和小企业主来说，它节省的是查找模板、核对法律条款、调整格式这些琐碎而耗时的“摩擦力”。技术真正的价值，往往就体现在这些被消除的细微摩擦之中。在使用时，请始终记住它的定位——一个高效的“草稿生成器”和“格式助手”，而对于法律文件的最终定稿和风险把控，专业的人脑判断依然不可替代。