Fiz Taxbot MCP

FIZ AI TaxBot-MCP服务器

葡萄牙税务助理的模型上下文协议服务器。

用任何语言提问🌍 — 以您的语言获取答案！

⚠️ 重要提示：MCP需要本地设置

MCP协议只能通过本地Node.js进程（stdio传输）工作。

如果您无法在本地运行Node.js，请使用 REST API 相反（见下文）。

______________________________________________________________________

🏠 选项1:MCP协议（克劳德桌面/代码）

要求：

• 本地安装Node.js
• 访问此存储库

1.克隆存储库并安装依赖项

git clone https://github.com/nortiboy555/fiz-taxbot-mcp.git
cd fiz-taxbot-mcp
npm install

或者以ZIP格式下载并解压。

2.获取API密钥

联系FIZ团队以接收您的API密钥。

3.配置克劳德桌面或克劳德代码

对于Claude Desktop：

编辑您的Claude Desktop配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

添加：

{
  "mcpServers": {
    "fiz-taxbot": {
      "command": "node",
      "args": ["/absolute/path/to/fiz-taxbot-mcp/index.js"],
      "env": {
        "FIZ_API_KEY": "your_api_key_here",
        "FIZ_API_URL": "https://af.fiz.co"
      }
    }
  }
}

克劳德代码：

创建 .mcp.json 项目根目录中的文件：

{
  "mcpServers": {
    "fiz-taxbot": {
      "command": "node",
      "args": ["/absolute/path/to/fiz-taxbot-mcp/index.js"],
      "env": {
        "FIZ_API_KEY": "your_api_key_here",
        "FIZ_API_URL": "https://af.fiz.co"
      }
    }
  }
}

⚠️ 重要:

• 替换 /absolute/path/to/fiz-taxbot-mcp/ 使用克隆存储库的实际路径！
• macOS示例： "/Users/username/fiz-taxbot-mcp/index.js"
• 示例窗口： "C:\\Users\\username\\fiz-taxbot-mcp\\index.js"
• 使用 https://af.fiz.co 用于生产

4.重新启动克劳德桌面/代码

MCP服务器将显示为可用工具 ask_portuguese_tax_question.

5.如何使用

在Claude Desktop/Code中，直接使用该工具：

Ask Portuguese tax question: "Какие ставки НДС в Португалии?"

或者在谈话中：

User: What are the VAT rates in Portugal?
Claude: [automatically uses ask_portuguese_tax_question tool]

支持的语言： 任何语言！用你的语言（英语、葡萄牙语、俄语、西班牙语、法语、德语、中文等）提问，并得到相同语言的答案。

税务专家：

• 阿尔萨斯葡萄酒行业协会IVA/VAT（税率、免税额、发票）
• 化学信息检索系统：IRS（个人所得税）
• 循环：IRC（公司税）
• SEGSOC：社会保障缴款
• 里蒂：社区内部交易
• RGIT：税务罚款和处罚
• 企业形象系统：印花税

______________________________________________________________________

🌐 选项2:REST API（通用）

无需本地设置！ 如果您无法在本地运行Node.js，请使用此选项。

端点

POST https://af.fiz.co/api/mcp/query

标头

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请求体

{
  "question": "Your tax question in any language",
  "specialist": "civa",     // Optional: force specific specialist
  "channel": "whatsapp",    // Optional: "web" | "whatsapp" | "telegram" | null (default: whatsapp)
  "userId": "user123"       // Optional: external user ID for multi-user scenarios
}

参数：

• question （必填）：任何语言的税务问题
• specialist （可选）：部队特定专家： civa, cirs, circ, segsoc, riti, rgit, cis
• channel （可选）：响应格式控制

- "web"：完整响应内联（无摘要/PDF处理） - "whatsapp" 或 "telegram"：冗长的回复→ 摘要+PDF（默认） - null 或省略：与 whatsapp （摘要+PDF用于长篇回复）

• userId （可选）：多用户机器人的外部用户标识符（例如，WhatsApp/Telegram）

响应格式

API返回针对信使通道优化的最小响应：

简短的回答 （≤400个字符）：

{
  "response": "Complete answer in your language (plain text, no markdown)"
}

冗长的回复 （>400个字符）：

{
  "response": "AI-generated summary with key points (≤400 chars, plain text)",
  "attachment": {
    "url": "https://blob.vercel-storage.com/pdf-abc123.pdf"
  }
}

澄清答复 （当专家不清楚时）：

{
  "response": "I need clarification. Which tax area does your question relate to?",
  "requiresClarification": true,
  "clarificationOptions": [
    {
      "id": "civa",
      "name": "IVA (VAT)",
      "description": "Value Added Tax questions"
    },
    {
      "id": "cirs",
      "name": "IRS",
      "description": "Personal Income Tax questions"
    }
  ]
}

笔记：

• 答案在 纯文本 （降价转换为WhatsApp/Telegram）
• 总结 突出完整答案中的关键点
• PDF 包含完整的详细答案，包括法律引用和格式
• PDF自动过期时间 7天 来自Vercel Blob存储
• 没有元数据字段：仅API退货 response 并且可选 attachment （无专家、对话ID、推荐信等）

响应处理：

• 阈值：400个字符（可通过数据库设置配置）
• 简短的回答 （≤400个字符）：内联返回完整答案
• 冗长的回复 （>400个字符）：人工智能生成的摘要+包含完整细节的PDF
• PDF TTL：7天（从Vercel Blob存储中自动删除）
• 频道：处理适用于 whatsapp, telegram，以及 null （默认）
• Web频道：设置 "channel": "web" 跳过处理并获得完整响应

示例

适用于任何语言！ 以下是俄语、葡萄牙语和英语的示例，但您可以使用西班牙语、法语、德语、中文、阿拉伯语或任何其他语言。

示例（curl-俄语）

curl -X POST https://af.fiz.co/api/mcp/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Какая ставка НДС в Португалии?"
  }'

示例（Python-葡萄牙语）

import requests

response = requests.post(
    "https://af.fiz.co/api/mcp/query",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "question": "Qual é a taxa de IVA em Portugal?"
    }
)

data = response.json()
print(data["response"])

示例（JavaScript-英语）

const response = await fetch("https://af.fiz.co/api/mcp/query", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    question: "What is the VAT rate in Portugal?"
  })
});

const data = await response.json();
console.log(data.response);

______________________________________________________________________

🧪 测试

测试REST API（生产版）

curl -X POST https://af.fiz.co/api/mcp/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Qual é a taxa de IVA em Portugal?"
  }'

在Claude桌面/代码中测试MCP

1. 打开克劳德桌面或克劳德代码
2. 开始新对话
3. 用任何语言询问您的税务问题
4. 克劳德将自动使用 ask_portuguese_tax_question 工具
5. 您将收到相同语言的答复

______________________________________________________________________

📚 文档

支持的语言

• 🌍 任何语言！ 用母语提问
• 💬 自动语言检测
• 🔄 用您使用的语言回答
• ✅ 测试语言：葡萄牙语、俄语、英语、西班牙语、法语、德语、中文等

税务专家

• 阿尔萨斯葡萄酒行业协会：IVA（增值税）-税率、免税额、发票
• 化学信息检索系统：IRS（个人所得税）
• 循环：IRC（公司税）
• SEGSOC：社会保障
• 里蒂：社区内部交易
• RGIT：罚款和处罚
• 企业形象系统：印花税

特性

• 🔄 对话连续性：自动继续您的税务对话
• 🎯 智能路由：将问题转交给合适的税务专家
• 📚 官方消息人士：所有答案均基于葡萄牙税法
• 🌐 多语言：以任何语言询问和接收答案
• 📄 聪明的回应：简短答案内联，长答案为AI摘要+详细PDF
• ☁️ PDF存储：Vercel Blob上的安全临时存储（7天TTL）

______________________________________________________________________

🛠️ 故障排除

克劳德桌面/代码中“找不到服务器”

1. 验证文件路径是绝对的（不是相对的）
2. 检查是否安装了Node.js： node --version
3. 配置更改后重新启动Claude Desktop/代码

“未经授权”错误

1. 验证您的API密钥是否正确
2. 如果您没有API密钥，请联系FIZ团队
3. 确保 FIZ_API_URL 设置为 https://af.fiz.co

工具未出现

1. 检查 .mcp.json 语法是有效的JSON
2. 验证 command 和 args 路径正确
3. 重新启动克劳德桌面/代码
4. 检查Claude的MCP设置/日志是否有错误

______________________________________________________________________

📝 许可证

MIT-FIZ 的© 2025年