biometric fingerprint analysis

生物指纹MCP服务器

用于生物特征指纹处理的安全模型上下文协议（MCP）服务器，为指纹采集、质量评估、模板生成、注册和验证提供高级工具。

状态：生产准备就绪，但存在轻微限制\ 版本: 1.0.0\ 最后更新: 2025-07-01

特性

• 安全处理：使用PBKDF2密钥推导对所有静态生物特征数据进行加密
• 质量评价：NFIQ 2.3集成（或模拟）用于指纹质量评分
• 遵从标准：ISO 19794-2和ANSI/INCITS 378模板格式
• 高级匹配：改进的BOZORTH3算法，具有0.91+自匹配精度
• MCP集成：与启用MCP的应用程序无缝集成
• 异步架构：高性能异步处理（每个指纹约400ms）
• 多个存储后端：具有重试逻辑和PostgreSQL支持的SQLite
• 输入验证：对所有用户输入进行全面验证
• 错误处理：具有特定错误类型的自定义异常层次结构

快速开始

1.克隆和设置

cd biometric-mcp
chmod +x setup_all.sh
./setup_all.sh

2.配置环境

创建一个 .env 文件：

# Required - must be 32-byte hex string
BIOMETRIC_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

# Optional - defaults shown
NFIQ2_PATH=/usr/local/bin/nfiq2
STORAGE_TYPE=sqlite
DB_PATH=./biometric.db
LOG_LEVEL=INFO

安全说明：在生产中使用强随机生成的加密密钥。

3.启动服务器

./start_server.sh

4.配置克劳德桌面

添加到您的Claude Desktop配置中：

{
  "biometric": {
    "command": "python",
    "args": ["path/to/biometric-mcp/server.py"],
    "transport": "stdio"
  }
}

MCP工具可用

1.捕获指纹

使用Gabor滤波器增强捕获和预处理指纹图像。

• base64图像、格式和DPI的输入验证
• 返回增强的图像和元数据

2.评估_质量

使用NFIQ 2.3或模拟评估指纹质量。

• 质量评分0-100
• 山脊清晰度和细节计数
• 入学建议

3.创建模板

生成符合ISO 19794-2标准的生物特征模板。

• 提取多达100个细节
• 包括奇点（核心、增量）
• 每个模板约630字节

4.报名表

为用户存储加密指纹模板。

• 100k迭代的PBKDF2密钥推导
• 每个用户支持多个手指
• 元数据存储

5.验证指纹

使用可配置的FAR阈值执行1:1指纹验证。

• 改进的BOZORTH3算法
• 自匹配精度：0.91+
• 处理时间：~25ms

项目结构

biometric-mcp/
├── server.py              # Main MCP server
├── config.py              # Configuration management
├── src/                   # Core modules
│   ├── fingerprint_tools.py    # Image processing
│   ├── quality_assessment.py   # NFIQ2 quality assessment
│   ├── template_generation.py  # Feature extraction
│   ├── storage.py             # Secure storage
│   ├── matching.py            # Biometric matching
│   ├── validation.py          # Input validation
│   ├── exceptions.py          # Custom exceptions
│   └── performance_config.py  # Performance tuning
├── tests/                 # Test files
├── test_samples/          # Test fingerprint images
├── requirements.txt       # Python dependencies
├── Dockerfile             # Container definition
├── docker-compose.yml     # Docker deployment
└── .env.template         # Environment template

先决条件

• Python 3.9+
• OpenCV（自动安装）
• NFIQ 2.3（可选，但建议使用-回到模拟）
• SQLite（默认）或PostgreSQL

安装

标准安装

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install NFIQ2 (optional)
./install_nfiq2.sh

Docker安装

docker-compose up --build

安全考虑

• 所有生物特征模板均使用带有PBKDF2密钥推导的Fernet（AES）加密
• 所有端点上的输入验证可防止注入攻击
• 元数据清理会删除敏感字段
• 在生产部署之前实施身份验证/授权
• 建议定期进行安全审计
• 遵循生物特征数据保护法规（GDPR、BIPA等）

性能指标

• 图像增强：~50ms
• 质量评价：~10ms
• 模板生成：约300毫秒
• 模板匹配：~25ms
• 总管道：每个指纹约400ms

测试

# Run validation tests
python test_validation.py

# Test full pipeline
python test_pipeline.py

# Test components directly
python test_direct_pipeline.py

已知限制

1. NFIQ2：如果未安装，则返回模拟
2. 认证：无内置身份验证（添加带身份验证的反向代理）
3. 测试数据：主要用合成指纹进行测试
4. 并发访问：SQLite可能存在高并发问题（使用PostgreSQL）

生产部署

1. 使用强加密密钥（32字节十六进制）
2. 安装NFIQ2以进行准确的质量评估
3. 添加身份验证层（OAuth2、API密钥）
4. 使用PostgreSQL进行并发访问
5. 监控性能指标
6. 定期安全审计

API文档

看 api_documentation.yaml 完整的OpenAPI规范。

故障排除

未找到NFIQ2

• 系统将回退到模拟模式
• 使用安装NFIQ2 ./install_nfiq2.sh

数据库锁定错误

• SQLite有并发限制
• 切换到PostgreSQL进行生产

比赛得分低

• 确保图像质量足够（>70）
• 检查DPI设置（建议500）
• 验证手指位置的一致性

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 确保所有测试通过
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅License.md

作者

亚伦·斯托里(astoreyai@gmail.com)

致谢

• NIST用于NFIQ2和BOZORTH3算法
• 图像处理工具的OpenCV社区
• MCP框架的FastMCP