基于MCP协议构建巴西数据集成服务器：架构设计与工程实践

1. 项目概述：一个面向巴西市场的MCP服务器实现

最近在探索如何让AI助手更深入地理解和使用特定区域的数据与服务时，我遇到了一个挺有意思的项目：jxnxts/mcp-brasil。简单来说，这是一个实现了Model Context Protocol (MCP)的服务器，专门用于接入和处理与巴西相关的各类数据源。

MCP，你可以把它理解为一个“翻译官”或者“适配器”协议。它的核心目标是让像 Claude、Cursor 这类AI助手能够安全、标准化地访问外部工具、数据库和API。想象一下，你直接告诉AI：“帮我查查圣保罗最近的天气”或者“分析一下巴西最近五年的GDP增长率”，如果没有MCP，AI可能束手无策，因为它无法直接连接气象局或统计局的数据库。而MCP服务器就负责把这些外部能力“翻译”成AI能理解和调用的“工具”。

mcp-brasil这个项目，顾名思义，就是聚焦于巴西这个特定市场。它不是一个单一功能工具，而是一个集成套件，可能打包了多个与巴西相关的数据源接口，比如官方统计数据、地理信息、公共API，甚至是本地化的商业服务。对于开发者、数据分析师或者任何需要让AI助手具备“巴西视角”的人来说，这个项目提供了一个即插即用的解决方案，省去了自己逐个对接API、处理认证和解析数据的繁琐过程。

这个项目的价值在于它的场景化集成。巴西作为一个重要的新兴市场，其数据有其独特性：葡萄牙语的数据格式、雷亚尔货币单位、特定的行政区划（州、市）、以及像CPF/CNPJ这样的本地标识符。一个通用的数据抓取工具可能无法很好地处理这些细节。而mcp-brasil的出现，意味着我们可以通过AI助手，以更自然、更高效的方式，进行巴西市场的调研、数据分析、报告生成甚至是商业决策辅助。

2. 核心架构与设计思路拆解

要理解mcp-brasil怎么工作，我们得先拆解一下MCP的基本架构，然后再看这个项目是如何在此基础上进行巴西化定制的。

2.1 MCP协议的核心三要素

MCP协议的设计非常清晰，主要围绕三个核心概念展开，理解了它们，就理解了整个项目的骨架：

1. 工具（Tools）：这是AI助手可以调用的具体功能单元。每个工具都有明确的名称、描述和参数定义。在mcp-brasil的上下文中，一个工具可能就是“查询巴西IBGE（地理统计局）的市级人口数据”，它的参数可能包括“州代码”、“城市名称”和“年份”。
2. 资源（Resources）：代表AI可以读取的静态或动态数据源。资源有一个唯一的URI（统一资源标识符）和一些元数据（如MIME类型）。例如，mcp-brasil可能暴露一个资源，其URI是brasil://ibge/states，内容就是巴西所有州的JSON列表。AI助手可以“读取”这个资源来获取信息。
3. 提示词模板（Prompts）：这是一些预定义的、参数化的提示词片段。它们不是直接执行操作，而是为AI助手提供结构化的对话起点或上下文。比如，mcp-brasil可以提供一个名为“分析巴西经济趋势”的提示词模板，当用户调用时，它会自动填入最近的经济指标数据资源URI，引导AI进行专业分析。

mcp-brasil项目的本质，就是根据巴西市场的需求，实现了一系列具体的Tools、Resources和Prompts，并将它们封装在一个符合MCP标准的服务器里。

2.2 项目设计的关键考量

在构建这样一个区域性MCP服务器时，作者jxnxts肯定考虑了以下几个关键点：

• 数据源的选择与聚合：巴西有哪些可靠、稳定且具有开放接口的数据源？常见的可能包括：
  • IBGE (Instituto Brasileiro de Geografia e Estatística)：核心的官方统计机构，提供人口、经济、社会等全方位数据。
  • BACEN (Banco Central do Brasil)：中央银行，提供金融、汇率、利率数据。
  • 巴西各州、市政府的开放数据门户。
  • 商业API：如汇率API、天气API的巴西节点等。
  • 项目的设计需要决定集成哪些源，是全部打包还是提供模块化选项。
• 本地化处理：
  • 语言：所有工具、资源的描述、返回的数据，是否支持或默认使用葡萄牙语？错误信息如何处理？
  • 格式：日期格式（DD/MM/YYYY）、数字格式（用逗号表示小数）、货币单位（R$）。
  • 编码：确保API通信和数据处理完全支持UTF-8，正确处理葡萄牙语中的重音字符（如ã, ç, é）。
• 认证与速率限制：许多官方API需要API Key，并有调用频率限制。mcp-brasil服务器需要妥善管理这些凭证（通常通过环境变量注入），并可能在内部实现请求队列或缓存，以优雅地处理速率限制，对AI助手层屏蔽这些复杂性。
• 错误处理与健壮性：当外部API不可用或返回意外数据时，服务器需要返回结构化的、对AI友好的错误信息，而不是直接崩溃或返回晦涩的HTTP代码。

注意：一个优秀的MCP服务器应该像一座坚固的桥梁，对AI侧（客户端）提供稳定、清晰的接口，而对数据源侧（服务端）则妥善处理各种网络波动、数据格式变异和业务逻辑异常。

3. 核心功能模块与实操要点

基于公开的MCP模式和实践，我们可以推断mcp-brasil可能包含以下几类核心功能模块。我会结合假设的实操场景来详细说明。

3.1 统计数据查询模块

这是最核心的模块，很可能围绕IBGE的API构建。

• 工具示例：
  • get_ibge_city_population：根据城市名称和年份查询人口。
  • search_ibge_indicator：搜索IBGE的指标体系（如GDP、失业率、通货膨胀率IPCA），并返回指定时间段的数据序列。
• 实操要点：
  • 参数设计：城市名称参数需要处理别名和重名情况。一个好的实践是同时接受城市名和州缩写（如 “São Paulo, SP”），或者先调用一个“列出城市”的资源来让AI辅助用户确定。
  • 数据缓存：人口、GDP这类年度数据变化不频繁，非常适合缓存。服务器可以在内存或Redis中缓存查询结果，设置合理的TTL（如24小时），大幅减少对IBGE API的调用并提升响应速度。
  • 返回格式：返回给AI的应该是结构化的JSON。例如，不仅包含数值，还应包含指标名称、单位、数据来源和时间戳，方便AI在组织回答时引用。

// 假设的工具调用返回结构 { "data": { "location": "São Paulo, SP", "year": 2023, "population": 12396372, "unit": "persons", "source": "IBGE Estimativas", "retrieved_at": "2024-05-27T10:30:00Z" } }

3.2 地理与行政区划模块

巴西的行政区划是数据分析的重要维度。

• 资源示例：
  • brasil://geo/states：一个资源，内容为巴西所有26个州和1个联邦区的列表，包含名称、缩写、代码、面积等。
  • brasil://geo/cities?state=SP：一个动态资源，获取圣保罗州所有城市的列表。
• 实操要点：
  • 数据预加载：州一级的数据相对稳定，可以在服务器启动时直接加载到内存中，作为静态资源提供，实现毫秒级响应。
  • 关联查询：这个模块需要与统计数据模块紧密关联。当AI使用get_ibge_city_population工具时，内部可能需要先通过本模块验证城市-州的对应关系。

3.3 金融数据模块

集成BACEN或市场汇率API。

• 工具示例：
  • get_currency_rate：获取美元兑雷亚尔（USD/BRL）或其他主要货币的实时或历史汇率。
  • get_selic_rate：查询巴西基准利率（SELIC）。
• 实操要点：
  • 实时性处理：汇率数据变化快。需要明确工具描述，说明数据是“近实时”（如15分钟延迟）还是“当日收盘价”。对于实时性要求高的场景，需要选择低延迟的API源，并考虑更短的缓存TTL（如1分钟）。
  • 历史数据：提供历史汇率查询时，参数“日期”的格式必须明确，并处理好节假日无数据的情况，返回友好的错误提示，如“所选日期为巴西节假日，金融市场休市，无汇率数据”。

3.4 本地化工具模块

处理巴西特有的标识或计算。

• 工具示例：
  • validate_cpf：验证一个CPF（个人税号）号码的格式和校验位是否有效。
  • format_brl：将一个数字格式化为巴西雷亚尔货币字符串（例如，1234.56->R$ 1.234,56）。
• 实操心得：
  • 校验算法的实现：CPF/CNPJ的校验算法是公开的，但实现时要特别注意细节。例如，输入可能包含标点（123.456.789-09），处理前需要净化。实现后，务必用官方提供的有效和无效示例进行充分测试。
  • 工具的双重作用：这类工具不仅提供实用功能，也作为“教学工具”帮助AI理解巴西的本土概念。当AI在对话中看到一个CPF号码时，它可以通过调用validate_cpf来确认其格式，甚至在用户输入错误时，可以基于校验算法推测可能的正确号码。

4. 服务器实现与部署实操

假设我们使用 Node.js (这是MCP生态的主流选择) 来仿建一个类似的mcp-brasil服务器。

4.1 项目初始化与依赖安装

首先，创建一个新项目并安装核心依赖。

# 创建项目目录 mkdir mcp-brasil-server cd mcp-brasil-server # 初始化Node.js项目 npm init -y # 安装核心依赖 # @modelcontextprotocol/sdk 是开发MCP服务器的官方SDK # axios 用于发起HTTP请求到巴西的各个API # dotenv 用于管理环境变量（如API密钥） # node-cache 用于简单的内存缓存 npm install @modelcontextprotocol/sdk axios dotenv node-cache

4.2 构建一个基础的MCP服务器框架

创建一个server.js文件，搭建服务器骨架。

const { Server } = require('@modelcontextprotocol/sdk/server/index.js'); const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js'); const axios = require('axios'); const NodeCache = require('node-cache'); require('dotenv').config(); // 初始化缓存，标准TTL设为300秒（5分钟），定期检查过期 const dataCache = new NodeCache({ stdTTL: 300, checkperiod: 60 }); // 创建Server实例 const server = new Server( { name: 'mcp-brasil', version: '0.1.0', }, { capabilities: { // 声明本服务器提供哪些能力 tools: {}, resources: {}, prompts: {}, }, } ); // 定义工具：获取美元兑雷亚尔汇率 server.setRequestHandler('tools/list', async () => { return { tools: [ { name: 'get_usd_brl_rate', description: '获取当前美元兑巴西雷亚尔(USD/BRL)的汇率。数据来源为巴西中央银行API。', inputSchema: { type: 'object', properties: { // 目前不需要输入参数 }, additionalProperties: false, }, }, ], }; }); // 处理工具调用 server.setRequestHandler('tools/call', async (request) => { const { name, arguments: args } = request.params; if (name === 'get_usd_brl_rate') { try { const cacheKey = 'usd_brl_rate_latest'; let rate = dataCache.get(cacheKey); if (rate === undefined) { // 缓存未命中，调用BACEN API // 注意：这里使用BACEN的SGS接口示例，需要申请Token const response = await axios.get( `https://api.bcb.gov.br/dados/serie/bcdata.sgs.10813/dados/ultimos/1?formato=json`, { headers: { 'Authorization': `Bearer ${process.env.BCB_API_TOKEN}`, 'Content-Type': 'application/json' } } ); if (response.data && response.data.length > 0) { rate = response.data[0].valor; dataCache.set(cacheKey, rate); } else { throw new Error('No rate data returned from API'); } } return { content: [ { type: 'text', text: `当前美元兑巴西雷亚尔的汇率为：1 USD = ${rate} BRL。\n（数据来源：巴西中央银行，缓存更新于${new Date().toISOString()}）`, }, ], }; } catch (error) { console.error('Error fetching exchange rate:', error); return { content: [ { type: 'text', text: `抱歉，获取汇率时出现错误：${error.message}。请稍后再试或检查网络连接。`, }, ], isError: true, }; } } return { content: [{ type: 'text', text: `未知工具：${name}` }], isError: true, }; }); // 启动服务器，使用标准输入输出传输（这是与AI客户端如Claude Desktop通信的标准方式） async function runServer() { const transport = new StdioServerTransport(); await server.connect(transport); console.error('MCP Brasil Server is running on stdio...'); } runServer().catch(console.error);

4.3 配置与运行

1. 创建环境变量文件：在项目根目录创建.env文件，存放敏感信息。

   BCB_API_TOKEN=your_bacen_api_token_here

2. 运行服务器：直接运行node server.js。但通常，MCP服务器是作为AI客户端的插件来运行的。例如，在Claude Desktop中，你需要将其配置为一个本地服务器工具。
3. 客户端配置（以Claude Desktop为例）：编辑Claude Desktop的配置文件（位于~/Library/Application Support/Claude/claude_desktop_config.json或类似路径）。

   { "mcpServers": { "brasil": { "command": "node", "args": ["/absolute/path/to/your/mcp-brasil-server/server.js"], "env": { "BCB_API_TOKEN": "your_bacen_api_token_here" } } } }

   重启Claude Desktop后，AI助手就能使用你定义的get_usd_brl_rate工具了。

5. 进阶功能与性能优化思考

一个基础服务器跑起来后，要考虑如何让它更健壮、更强大。

5.1 实现资源（Resources）提供

除了工具，实现资源能让AI直接“阅读”数据。例如，提供一个巴西节日列表资源。

// 在server.js中增加资源处理 server.setRequestHandler('resources/list', async (request) => { const { parent } = request.params; // 如果请求根资源列表 if (!parent) { return { resources: [ { uri: 'brasil://holidays/2024', name: '巴西2024年法定节假日列表', description: '巴西全国范围的法定节假日日期及名称', mimeType: 'application/json', }, ], }; } return { resources: [] }; }); server.setRequestHandler('resources/read', async (request) => { const { uri } = request.params; if (uri === 'brasil://holidays/2024') { // 这里可以硬编码，也可以从外部API获取 const holidays2024 = [ { date: '2024-01-01', name: 'Confraternização Universal' }, { date: '2024-04-21', name: 'Tiradentes' }, { date: '2024-05-01', name: 'Dia do Trabalhador' }, // ... 其他节日 ]; return { contents: [ { uri: uri, mimeType: 'application/json', text: JSON.stringify(holidays2024, null, 2), }, ], }; } return { contents: [{ uri: uri, mimeType: 'text/plain', text: 'Resource not found.' }], isError: true, }; });

5.2 缓存策略精细化

针对不同类型的数据，采用不同的缓存策略，这是提升性能和降低API成本的关键。

在代码中，可以使用不同的缓存命名空间或实例来管理：

const staticCache = new NodeCache({ stdTTL: 86400 }); const dailyCache = new NodeCache({ stdTTL: 43200 }); const realtimeCache = new NodeCache({ stdTTL: 60 });

5.3 错误处理与降级方案

网络请求总有可能失败，必须有完善的错误处理。

• 结构化错误返回：始终向AI返回结构化的错误信息，而不是原始的异常堆栈。
• 重试机制：对于暂时性网络错误（如5xx状态码），可以实现指数退避重试。
• 降级数据源：如果主API（如BACEN）不可用，是否可以回退到次要的、可能免费但延迟更高的API？在工具描述中应说明数据的可能延迟。
• 缓存兜底：当API完全失败时，如果缓存中有过期的数据，可以考虑返回这些“陈旧”数据，并明确告知AI“数据可能不是最新的”。这比直接返回错误有时更有用。

// 一个包含重试和缓存兜底的请求函数示例 async function fetchWithRetryAndFallback(apiCall, cacheKey, ttl, maxRetries = 2) { let lastError; for (let i = 0; i <= maxRetries; i++) { try { const data = await apiCall(); dataCache.set(cacheKey, data, ttl); return { data, isFresh: true }; } catch (error) { lastError = error; if (i < maxRetries) { await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, i))); // 指数退避 } } } // 全部重试失败，尝试返回缓存（即使是过期的） const cachedData = dataCache.get(cacheKey); if (cachedData) { console.warn(`Returning stale data for ${cacheKey} after API failure.`); return { data: cachedData, isFresh: false, error: lastError.message }; } // 缓存也没有，彻底失败 throw lastError; }

6. 常见问题与排查技巧实录

在实际开发和运行mcp-brasil这类MCP服务器时，你肯定会遇到一些典型问题。

6.1 连接与通信问题

• 问题：AI客户端（如Claude Desktop）无法连接到自定义服务器，或连接后工具列表为空。
• 排查：
  1. 检查传输层：MCP服务器默认使用stdio（标准输入输出）与客户端通信。确保你的服务器脚本是可执行的，并且没有在启动初期就崩溃退出。在服务器启动后添加console.error('Server started')有助于在客户端日志中确认。
  2. 检查客户端配置：确认客户端配置文件中的command和args路径绝对正确。对于Node.js脚本，command必须是node或node.exe的完整路径。
  3. 验证服务器响应：在tools/list和resources/list的处理程序中，确保返回的JSON格式完全符合MCP协议规范。一个常见的错误是属性名拼写错误（如inputSchema写成input）。
  4. 查看客户端日志：Claude Desktop等客户端通常有日志输出位置。查看这些日志，里面往往有连接失败或协议错误的详细信息。

6.2 工具调用失败问题

• 问题：工具列表能看到，但调用时失败，返回权限错误或网络错误。
• 排查：
  1. 环境变量：这是最常出问题的地方。确保你的.env文件已加载，或者客户端配置中的env字段已正确设置API密钥。在服务器代码开头打印process.env.BCB_API_TOKEN（当然正式版要删掉）可以验证。
  2. API端点与参数：手动用curl或 Postman 测试你集成的巴西API，确认端点URL、请求头、参数格式（尤其是日期格式）都正确。巴西很多官方API日期格式是dd/MM/yyyy，与常见的yyyy-MM-dd不同。
  3. 速率限制：如果你短时间内频繁调用，可能触发API的速率限制。服务器日志中会收到429状态码。此时必须实现请求队列或更积极的缓存。

6.3 数据格式与编码问题

• 问题：AI助手接收到的数据出现乱码，或者无法正确解析JSON。
• 排查：
  1. 字符编码：确保你的Node.js脚本文件保存为UTF-8格式。在HTTP请求和响应中，明确设置Content-Type: application/json; charset=utf-8。
  2. JSON序列化：使用JSON.stringify()返回数据前，确保对象是纯JavaScript对象，不包含循环引用或特殊类型（如Date对象、函数）。对于Date，最好先转换为ISO字符串。
  3. 文本格式化：返回给AI的text字段，虽然是字符串，但内容应尽可能清晰、结构化。使用\n换行、**加粗**（如果AI支持Markdown）等方式提升可读性。

6.4 性能与稳定性问题

• 问题：工具调用响应慢，或者服务器运行一段时间后内存占用过高。
• 排查与优化：
  1. 缓存滥用：检查缓存键（Cache Key）的设计。确保不同参数的工具调用对应不同的缓存键，否则会导致数据错乱。例如，查询“São Paulo”和“Rio de Janeiro”的人口应该缓存为两个不同的键。
  2. 内存泄漏：如果使用内存缓存（如node-cache），注意不要缓存过大的对象（如整个巴西的城市数据集），或者设置过长的TTL导致缓存无限增长。定期监控服务器内存使用情况。
  3. 异步操作阻塞：确保所有I/O操作（网络请求、文件读取）都是异步的，不要使用同步函数阻塞事件循环。
  4. 日志与监控：为关键操作（API调用、缓存命中/未命中、错误）添加日志。这不仅是调试的需要，也是后期监控服务器健康度和性能的基础。

构建一个像mcp-brasil这样的区域性MCP服务器，技术难点往往不在协议本身，而在于对目标区域生态的深入理解、对数据源的可靠集成，以及工程上的健壮性设计。它要求开发者既是“巴西通”，又是“连接器工程师”。当你看到AI助手能流畅地引用巴西最新经济数据，或者准确地解释一个本地概念时，背后正是这样一个精心构建的服务器在默默工作。