Fisc MCP

FiscAI MCP

FISCMCP项目的专业自述（西班牙语）。本文档解释了该项目的功能、如何安装和运行它、如何配置它以及开发和部署步骤。

描述

Fiscai MCP是一个工具服务器，旨在为墨西哥的微型和小型企业提供财政和金融咨询。组合：

• 用于语言生成和嵌入的人工智能引擎（谷歌双子座）。
• 用于RAG（Retrieval-Augmented Generation）的语义搜索和存储后端。
• 工具：财政建议、辅助聊天、风险分析、文件搜索、正式化路线图、增长预测（ML模型）和地图开放（Deep Links）。

内核是用 fastmcp （实例） mcp 英语 src/main.py)并提供可选的HTTP服务器(src/http_server.pyProbar终点休息。

主要特征

• 通过RAG（嵌入+相关文件）定制税收建议。
• 带有自动意图检测的辅助聊天（例如，为银行或卫星打开地图）。
• SUPABASE中税收文件的语义搜索。
• 财政风险分析和正式化路线图的生成。
• 使用训练模型预测业务增长 src/modelDemo).

存储库结构（摘要）

• run_server.py -运行MCP服务器的入口点（FASTMCP模式）。
• run_http_server.py -运行HTTP服务器（Fastapi+Uvicorn）的脚本。
• server.py -准备部署的文件（导出 mcp 用于自动探测器）。
• requirements.txt -项目依赖性。
• src/ -主要源代码：

- main.py -注册工具(@mcp.tool() y提示 @mcp.prompt()). - http_server.py -用于测试工具的REST API。 - gemini.py -客户和与谷歌双子座（LLM&Embeddings）的集成。 - supabase_client.py -Subase客户端（语义搜索、聊天历史等）。 - places.py -与Google Places集成以搜索位置。 - config.py -加载环境变量和验证。 - modelDemo/ -ML模型的数据和示例脚本（培训和演示）。

• test_*.py -单元和集成测试套件（多个文件） test_*.py).

要求

• Python 3.10+（首选）。
• 匹普。
• 访问使用的外部API：

- 谷歌双子座（clave GEMINI_API_KEY) - Supabase（URL y服务角色键） - 谷歌Places API（用于网站搜索）

列出的依赖项 requirements.txt。此外，建议为HTTP服务器安装 fastapi y uvicorn[standard].

环境变量（主要）

在文件中配置 .env 在项目的根或系统环境中：

• SUPABASE_URL-SUPABASE项目的URL。
• SUPABASE_SERVICE_ROLE_KEY——SUPABASE的服务角色键（参见RPC/特权）。
• GEMINI_API_KEY-API密钥对Google GEMINI。
• EXPO_PUBLIC_GOOGLE_MAPS_API_KEY o GOOGLE_MAPS_API_KEY-段落 places.
• 端口-HTTP服务器的端口（默认） 8000).
• NODE_ENV-- development 哦 production.
• 可选：

- 双子座模型-双子座模型的名称（默认 gemini-2.5-flash). - Gemini_Fallback_Models-用逗号分隔的备份模型列表（默认） gemini-2.5-flash-lite,gemini-2.5-pro,gemini-3.1-pro-preview,gemini-3-flash-preview,gemini-3.1-flash-lite-preview). - Gemini_Embed_Model-嵌入模型（默认） gemini-embedding-001). - Embed_dim-嵌入的维度（默认） 768). - 相似性阈值-相似性阈值（默认） 0.6). - Topk_Documents-要恢复的文档数量（默认） 6).

重要提示：不要在公共存储库中发布密钥。在您的部署平台上使用秘密。

安装（本地）

1. 克隆存储库并导航到文件夹：

cd C:\Users\Owner\Downloads\FiscMCP

1. （可选）创建和激活虚拟环境：

python -m venv .venv; .\.venv\Scripts\Activate.ps1

1. 安装依赖项：

pip install -r requirements.txt
# Recomendado para la API HTTP (si vas a usarla):
pip install fastapi uvicorn[standard]

1. 创建新文件 .env 遵循“环境变量”部分并添加必要的键。

执行

执行该项目有两种主要方式：

1. MCP 服务器（ FastMCP 模式）

• 使用（从回购的根）：

python run_server.py

该脚本添加 src 铝 PYTHONPATH 并执行 main() 英语 src/main.py，它记录工具并执行 mcp.run().

1. Servidor HTTP（FastAPI）——准认证端点REST

• 使用（从回购的根）：

python run_http_server.py

• El script美国 uvicorn 内部并将展示：

- 健康：http://localhost:8000/health - 互动文档（Swagger/OpenAPI）：http://localhost:8000/docs - 主要端点： /api/fiscal-advice, /api/chat, /api/risk-analysis, /api/search, /api/user-context.

如果您更改端口，请定义 PORT 英语 .env.

端点（示例）

1. 健康检查

# Obtener estado
Invoke-RestMethod -Method Get -Uri http://localhost:8000/health

1. 申请税务建议（示例）

$body = @{ actividad = 'Ventas en línea'; ingresos_anuales = 300000; estado = 'CDMX' } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri http://localhost:8000/api/fiscal-advice -Body $body -ContentType 'application/json'

1. 与助理聊天

$body = @{ message = '¿Dónde está un Banorte cerca de Reforma?'; user_id = 'guest' } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri http://localhost:8000/api/chat -Body $body -ContentType 'application/json'

1. 文档语义搜索

$body = @{ query = 'beneficios régimen RESICO'; limit = 5 } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri http://localhost:8000/api/search -Body $body -ContentType 'application/json'

它是如何工作的（高水平）

• src/main.py 注册多个工具，例如 @mcp.tool() y提示con @mcp.prompt() 实现业务逻辑（RAG、聊天、风险分析、路线图等）。
• src/gemini.py 它封装了与谷歌双子座的集成：生成嵌入、提示符以及聊天和RAG逻辑。
• src/supabase_client.py 封装对Supabase的访问-包括用于语义搜索的RPC(match_fiscai_documents)以及聊天历史和用户的表格。
• src/places.py 使用Google Places API搜索机构并生成 deepLink 对于移动应用程序(fiscai://...)哦。
• src/config.py 集中配置并验证关键环境变量。

开发和测试

• REPO包含测试 test_*.py 用于基本单元测试。您可以使用 pytest.

pip install pytest
pytest -q

• 对于迭代开发，我们建议使用虚拟环境，并在更改代码时重新启动服务器。

调试和常见问题

• 错误：“缺少环境变量…”-请确保创建 .env 骗局 SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, GEMINI_API_KEY y EXPO_PUBLIC_GOOGLE_MAPS_API_KEY 美国 places.
• 双子座错误：验证 GEMINI_API_KEY 它是有效的，并且配置的模型存在于您的帐户中。
• Subase：如果RPC函数失败，请验证名称(match_fiscai_documents, match_documents)它们存在于你的Subase项目中。

安全

• 永远不要上去 SUPABASE_SERVICE_ROLE_KEY 你 GEMINI_API_KEY 公共仓库。
• 对于制作，它使用托管平台（Vercel、Railway、Fly、AWS等）管理的秘密，而不是 .env 在迪斯科舞厅。

部署（快速建议）

• Plataformas推荐的平台包括：铁路、Fly.io、Azure应用服务、DigitalOcean应用平台。
• 建议：部署HTTP服务器(run_http_server.py)隐藏代理并与供应商管理秘密。
• 考虑使用Docker容器进行可移植性（不包括DockerFile-可以轻松添加）。

争议

• 打开建议或错误的问题。
• Fork+PR：添加功能更改测试。
• 遵循现有的编码风格并记录 README.md 当你改变公众行为时。

建议采取以下步骤

• 添加一个 Dockerfile y docker-compose 促进当地部署。
• 添加验证链接和测试的CI（GitHub操作）。
• 添加示例 .env.example 具有不敏感的变量（变量名称和描述）。
• 提高测试覆盖率 src/gemini.py （模拟响应）y src/supabase_client.py （模仿RPC）。

______________________________________________________________________

文摘：分析了该项目的结构和主要代码(src/main.py, src/http_server.py, src/gemini.py, src/supabase_client.py, src/places.py, src/config.py)我用西班牙语准备了这份自述，其中包括安装、配置和使用指南。如果你愿意，我可以：

• 添加文件 .env.example 使用列出的环境变量进行回购。
• C_创建 Dockerfile y docker-compose.yml 以身作则。
• 为本地开发添加检查脚本（makefile/ps1）。

告诉我你更喜欢什么，然后我执行它。