Firmia (Bacoco)

Firmia-法国企业数据集成

Firmia是一个MCP（模型上下文协议）服务器，提供对来自多个官方来源的法国企业数据的统一访问，包括INSEE、Banque de France和INPI。Firmia通过将法国公司数据整合到一个强大的界面中，简化了商业智能。

目录

• 特性
• 快速开始
• 安装
• 配置
• 用法
• Web用户界面
• 可用工具
• API响应示例
• 建筑
• 数据源
• 演出
• 发展
• 故障排除
• 贡献
• 许可证

特性

• 🏢 多源综合：通过单一接口访问INSEE、法国银行和INPI的数据
• 🔍 企业搜索：在所有数据源中按名称、SIREN或SIRET搜索
• 📊 综合数据：获取公司信息、财务和知识产权数据
• ⚡ 性能优化：内置缓存和速率限制，实现最佳性能
• 🔒 类型安全：完全支持TypeScript，具有严格的类型检查
• 🛡️ 错误处理：具有详细错误消息的稳健错误处理
• 🔄 自动检索：瞬态故障的智能重试逻辑
• 📈 费率限制管理：跨API的智能配额管理
• 🌐 Web用户界面：用于测试和调试的简单web界面
• 🚀 一键启动：用一个脚本开始一切

快速开始

开始使用Firmia的最快方法：

# Clone and launch
git clone https://github.com/bacoco/Firmia.git
cd Firmia
./launch.sh

这将：

1. 安装所有依赖项
2. 构建项目
3. 启动MCP服务器
4. 启动web UI
5. 自动打开浏览器

🌐 Web用户界面: http://localhost:3001\ 📡 MCP服务器: http://localhost:8080

安装

先决条件

• Node.js 18.0.0或更高版本
• npm 8.0.0或更高版本
• MCP客户端（Claude Desktop、VS Code扩展或其他MCP兼容客户端）

分步安装

1. 克隆存储库

git clone https://github.com/bacoco/Firmia.git
cd Firmia

1. 安装依赖项

npm install

1. 配置环境变量

# Copy the example environment file
cp .env.example .env

# Edit .env with your API credentials
# See Configuration section for details

1. 构建项目

npm run build

1. 添加到MCP客户端配置

对于Claude Desktop，请添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "firmia": {
      "command": "node",
      "args": ["/path/to/Firmia/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

配置

获取API密钥

1.INSEE API

1. 访问 INSEE开发者门户
2. 创建帐户（免费）
3. 创建新应用程序
4. 订阅“Sirene-V3”API
5. 复制您的消费者密钥和消费者秘密

2.法国银行API

1. 联系法国银行 webstat@banque-france.fr
2. 请求访问其企业数据API
3. 您将通过安全电子邮件收到凭据

3.INPI API

1. 访问 INPI数据门户
2. 创建开发人员帐户
3. 请求API访问：

- 商标数据库 - 专利数据库 - 设计数据库

1. 注意您的API密钥和客户端凭据

环境变量

创建一个 .env 具有以下配置的文件：

# INSEE API Configuration
INSEE_API_KEY=your_insee_api_key
INSEE_API_URL=https://api.insee.fr/entreprises/sirene/V3

# Banque de France API Configuration
BANQUE_FRANCE_API_KEY=your_api_key
BANQUE_FRANCE_USERNAME=your_username
BANQUE_FRANCE_PASSWORD=your_password
BANQUE_FRANCE_API_URL=https://api.banque-france.fr

# INPI API Configuration
INPI_API_KEY=your_api_key
INPI_CLIENT_ID=your_client_id
INPI_CLIENT_SECRET=your_client_secret
INPI_API_URL=https://api.inpi.fr

# Cache Configuration
CACHE_TTL=3600                    # Cache time-to-live in seconds (default: 1 hour)
CACHE_CHECK_PERIOD=600            # Cache cleanup interval in seconds

# Rate Limiting Configuration (requests per hour)
RATE_LIMIT_INSEE=5000             # INSEE API rate limit
RATE_LIMIT_BANQUE_FRANCE=1000    # Banque de France API rate limit
RATE_LIMIT_INPI=2000              # INPI API rate limit

# MCP Server Configuration
MCP_SERVER_NAME=firmia
MCP_SERVER_VERSION=1.0.0
MCP_LOG_LEVEL=info                # Options: debug, info, warn, error

# Development Settings
NODE_ENV=development              # Options: development, production
DEBUG=firmia:*                    # Enable debug logging

用法

启动服务器

# Development mode with hot reload
npm run dev

# Production mode
npm run build
npm start

# With custom environment file
NODE_ENV=production npm start

# Or use the launch script (recommended)
./launch.sh

测试连接

选项1:Web UI（推荐）

./launch.sh
# Opens http://localhost:3001 automatically

选项2:MCP客户端

{
  "tool": "get_api_status",
  "params": {}
}

Web用户界面

Firmia包括 简单的web界面 用于测试和调试MCP服务器，而不需要单独的MCP客户端。

特性

• 🎮 交互式测试：使用用户友好的界面测试所有MCP工具
• 📊 实时状态：监控MCP服务器和API状态
• 🔄 服务器控件：直接从UI启动/停止MCP服务器
• 📋 结果显示：查看格式化的响应和错误消息
• ⚡ 自动刷新：每10秒自动更新一次状态

快速启动

# Start everything with one command
./launch.sh

# Or manually:
npm run build
cd web-ui && npm install && npm start

Web UI组件

状态仪表板：

• MCP服务器状态（运行/停止）
• API健康监测
• 速率限制跟踪

工具测试：

• 搜索企业：在所有API中搜索测试公司
• 企业详细信息：通过SIREN获取详细的公司信息
• API状态：检查所有连接的API的运行状况和速率限制

结果面板：

• 实时响应显示
• 错误处理与调试
• 请求/响应历史记录

截图

主仪表板：

• 干净、现代的界面，带状态卡
• 实时服务器监控
• 一键式测试工具

搜索界面：

• 具有过滤选项的企业搜索
• 支持公司名称和SIREN号码
• 可配置的结果限制

结果显示：

• 格式化JSON响应
• 颜色编码的成功/错误状态
• 带时间戳的请求历史记录

配置

Web UI可以通过环境变量进行配置：

# Web UI port (default: 3001)
WEB_UI_PORT=3001

# MCP Server port (default: 8080)
MCP_PORT=8080

# Auto-open browser (default: true)
AUTO_OPEN_BROWSER=true

发展

要开发Web UI，请执行以下操作：

# Install dependencies
cd web-ui && npm install

# Start in development mode
npm run dev

# The UI will auto-reload on changes

Web UI使用：

• 前端：HTML5、CSS（顺风）、香草JavaScript
• 后端：Express.js服务器
• 沟通：带有MCP服务器的REST API

可用工具

1.搜索_企业

在多个数据源中搜索法国企业。

参数：

请求示例：

{
  "tool": "search_enterprises",
  "params": {
    "query": "Airbus",
    "source": "all",
    "includeHistory": false,
    "maxResults": 5
  }
}

2.获取企业详细信息

通过SIREN获取特定企业的详细信息。

参数：

请求示例：

{
  "tool": "get_enterprise_details",
  "params": {
    "siren": "383474814",
    "source": "all",
    "includeFinancials": true,
    "includeIntellectualProperty": true
  }
}

3.获取pi_status

检查连接的API的状态和速率限制。

请求示例：

{
  "tool": "get_api_status",
  "params": {}
}

API响应示例

搜索响应

{
  "success": true,
  "results": [
    {
      "source": "insee",
      "data": [
        {
          "siren": "383474814",
          "name": "AIRBUS",
          "legalForm": "Société européenne",
          "address": {
            "street": "2 ROND POINT EMILE DEWOITINE",
            "postalCode": "31700",
            "city": "BLAGNAC"
          },
          "activity": {
            "code": "30.30Z",
            "description": "Construction aéronautique et spatiale"
          },
          "employees": 5000,
          "creationDate": "1970-01-01"
        }
      ]
    },
    {
      "source": "banque-france",
      "data": [
        {
          "siren": "383474814",
          "name": "AIRBUS",
          "rating": "AAA",
          "lastFinancialYear": 2023
        }
      ]
    }
  ]
}

企业详细信息响应

{
  "success": true,
  "siren": "383474814",
  "details": {
    "insee": {
      "identification": {
        "siren": "383474814",
        "name": "AIRBUS",
        "tradeName": "AIRBUS COMMERCIAL AIRCRAFT",
        "legalForm": "Société européenne",
        "registrationDate": "1970-01-01",
        "capital": 2704000
      },
      "establishments": [
        {
          "siret": "38347481400048",
          "isHeadOffice": true,
          "address": {
            "street": "2 ROND POINT EMILE DEWOITINE",
            "postalCode": "31700",
            "city": "BLAGNAC"
          }
        }
      ]
    },
    "banque-france": {
      "financials": [
        {
          "year": 2023,
          "revenue": 65446000000,
          "netIncome": 3789000000,
          "totalAssets": 138503000000,
          "employees": 134267
        }
      ],
      "rating": {
        "score": "AAA",
        "outlook": "Stable",
        "lastUpdate": "2024-01-15"
      }
    },
    "inpi": {
      "trademarks": [
        {
          "id": "4234567",
          "name": "AIRBUS",
          "classes": [12, 39, 42],
          "registrationDate": "2010-03-15",
          "status": "active"
        }
      ],
      "patents": [
        {
          "id": "EP2234567",
          "title": "Aircraft wing optimization system",
          "applicationDate": "2019-06-20",
          "status": "granted"
        }
      ]
    }
  }
}

错误响应示例

{
  "success": false,
  "error": "ENTERPRISE_NOT_FOUND",
  "details": {
    "message": "No enterprise found with SIREN: 123456789",
    "suggestions": ["Did you mean: 123456788?"]
  }
}

建筑

mcp-firms/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── adapters/             # API adapters for each data source
│   │   ├── index.ts          # Adapter factory and interfaces
│   │   ├── insee.ts          # INSEE API adapter
│   │   ├── banque-france.ts  # Banque de France adapter
│   │   └── inpi.ts           # INPI adapter
│   ├── cache/                # Caching layer
│   │   └── index.ts          # Cache implementation
│   ├── rate-limiter/         # Rate limiting implementation
│   │   └── index.ts          # Rate limiter with per-API quotas
│   ├── types/                # TypeScript type definitions
│   │   └── index.ts          # Shared types and interfaces
│   └── utils/                # Utility functions
│       └── index.ts          # Helper functions
├── tests/                    # Test suite
│   ├── adapters/            # Adapter tests
│   ├── integration/         # Integration tests
│   └── utils.test.ts        # Utility tests
├── docs/                     # Documentation
│   ├── API.md               # API adapter documentation
│   ├── CONTRIBUTING.md      # Contribution guidelines
│   └── examples/            # Usage examples
└── dist/                    # Compiled JavaScript (generated)

数据源

INSEE（国家统计和经济研究所）

• 数据覆盖：所有法国企业和机构
• 更新频率：每日
• 关键数据点:

- 公司标识（SIREN/SIRET） - 法律信息和结构 - 业务分类（NAF/APE代码） - 机构地点和员工 - 行政状态和变更

法国银行

• 数据覆盖：具有重大经济活动的公司
• 更新频率：季度
• 关键数据点:

- 财务报表（3-5年历史） - 信用评级和风险评估 - 银行关系 - 经济指标 - 付款行为

INPI（国家工业产权研究所）

• 数据覆盖：法国的所有知识产权注册
• 更新频率：每周
• 关键数据点:

- 商标（国家和欧盟） - 专利（法国和欧洲） - 工业设计 - 公司注册 - 知识产权诉讼历史

演出

缓存策略

• 内存缓存 带可配置TTL
• 缓存密钥格式: source:operation:params
• 默认TTL：1小时（可配置）
• 缓存失效：基于TTL的自动

速率限制

• Per-API速率限制 具有可配置的配额
• 令牌桶算法 用于平滑速率限制
• 自动重试 指数回退
• 速率限制标题 传递给响应

响应时间

• 缓存响应：\<10ms
• 欧洲工商管理学院API：200-500毫秒
• 法国银行API：300-800ms
• API国际石油学会：400-1000毫秒
• 多源查询：并行执行

发展

先决条件

• Node.js 18+支持TypeScript
• Git用于版本控制
• API测试密钥

设置开发环境

# Clone the repository
git clone https://github.com/bacoco/Firmia.git
cd Firmia

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Type checking
npm run typecheck

# Run in development mode
npm run dev

项目脚本

• npm run build -将TypeScript构建为JavaScript
• npm run dev -使用热重载运行
• npm test -运行测试套件
• npm run test:watch -在监视模式下运行测试
• npm run test:coverage -生成覆盖率报告
• npm run lint -运行ESLint
• npm run lint:fix -修复掉毛问题
• npm run typecheck -运行TypeScript编译器检查

故障排除

常见问题

1.身份验证错误

问题: AUTHENTICATION_FAILED 错误 解决方案:

• 验证中的API密钥 .env 文件
• 检查API密钥权限
• 确保钥匙未过期

2.超出费率限制

问题: RATE_LIMIT_EXCEEDED 错误 解决方案:

• 等待速率限制重置（如响应所示）
• 降低请求频率
• 增加缓存TTL
• 在中配置较低的速率限制 .env

3.未找到企业

问题: ENTERPRISE_NOT_FOUND 错误 解决方案:

• 验证SIREN格式（9位数字）
• 检查公司是否在法国注册
• 请尝试按名称搜索

4.连接问题

问题: SERVICE_UNAVAILABLE 错误 解决方案:

• 检查互联网连接
• 验证API端点是否可访问
• 检查API是否正在维护中

5.缓存问题

问题：数据陈旧或不正确 解决方案:

• 重新启动服务器以清除缓存
• 减少频繁更新数据的缓存TTL
• 检查缓存配置

调试模式

启用调试日志以进行故障排除：

DEBUG=firmia:* npm run dev

这将显示：

• API请求/响应详细信息
• 缓存命中/未命中信息
• 利率限制决策
• 错误堆栈跟踪

贡献

我们欢迎捐款！请看 贡献.md 有关以下内容的详细信息：

• 建立开发环境
• 代码风格指南
• 添加新的API适配器
• 提交拉取请求
• 报告问题

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• INSEE提供SIRENE API
• 法国银行金融数据访问
• INPI知识产权数据
• 协议规范的MCP社区
• 贡献者和维护者

支持

• 📧 电子邮件：support@firmia.dev
• 💬 不一致： 加入我们的服务器
• 🐛 问题：
• 📖 维基： 文档Wiki