MCP Abstract

MCP 服务器 - 摘要

关于

MCP服务器 - 摘要 这是一个可投入生产的模型上下文协议（MCP）服务器，提供与（其他系统/服务）的无缝集成 摘要的其全面的数据验证、丰富化和智能服务套件。该服务器采用企业级架构构建，使AI助手和代理能够验证电子邮件和电话号码、丰富公司数据、执行IP地理定位、进行货币转换等更多功能——所有这些都通过类型安全、以异步优先的接口实现。

特点/特性

• 全面API覆盖完成15+个抽象API端点的完整实现
• 强类型（或严格类型）所有响应都使用 Pydantic 模型以确保类型安全
• HTTP传输支持带健康检查端点的流式HTTP
• 异步/等待基于aiohttp构建，以实现高性能
• 类型安全完全符合 mypy 严格模式
• 准备就绪，可投入生产Docker支持、全面测试、代码规范检查
• 开发者友好Makefile 命令、自动格式化、快速反馈

支持的API

数据验证

• 电子邮件验证 - 验证电子邮件可送达性，检测一次性电子邮件
• 电话号码验证 - 验证电话号码，识别运营商
• 增值税验证 - 验证欧盟增值税号

IP Intelligence（知识产权情报）

• IP地理定位 - 从IP地址获取位置
• 带安全功能的IP地理定位 - 通过VPN/代理/数据中心检测获取位置
• IP信息 - ISP（互联网服务提供商）、ASN（自治系统编号）和连接详情

时间与地点

• 时区 - 从位置或坐标获取时区
• 时区转换 - 在不同时区之间转换时间
• 假期 - 获取按国家/年份划分的公共假期

金融

• 汇率 - 实时货币汇率
• 货币转换 - 在不同货币之间转换金额

网络与商业

• 公司充实（或公司丰富化） - 从域名获取公司数据
• 网络抓取（或网页数据抓取） - 从网站中提取结构化数据
• 屏幕截图 - 生成网站截图

安装

使用紫外线（推荐）

# Install dependencies
uv pip install -e .

# Install with dev dependencies
uv pip install -e . --group dev

使用 pip

pip install -e .

配置

重要的抽象API使用 不同服务对应不同的API密钥您需要为想要使用的每个服务获取单独的密钥。

设置

1. 从以下位置获取您的API密钥： 摘要API仪表板

- 每个服务（电子邮件、电话、IP等）都有自己的API密钥 - 您只需要为计划使用的服务获取密钥

1. 创建一个 .env 项目根目录下的文件：

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

# Edit .env and add your service-specific keys

1. 将你的密钥添加到 .env：

# Example: If you only use IP geolocation and phone validation
ABSTRACT_IP_API_KEY=your_ip_key_here
ABSTRACT_PHONE_API_KEY=your_phone_key_here

可用的服务密钥名称：

• ABSTRACT_EMAIL_API_KEY - 电子邮件验证
• ABSTRACT_PHONE_API_KEY - 电话验证
• ABSTRACT_VAT_API_KEY - 增值税验证
• ABSTRACT_IP_API_KEY - IP地理位置定位（也用于VPN检测）
• ABSTRACT_TIMEZONE_API_KEY - 时区服务
• ABSTRACT_HOLIDAYS_API_KEY - 节假日查询
• ABSTRACT_EXCHANGE_API_KEY - 货币汇率
• ABSTRACT_COMPANY_API_KEY - 公司增值
• ABSTRACT_SCRAPE_API_KEY - 网络爬虫（或网页抓取）
• ABSTRACT_SCREENSHOT_API_KEY - 截图生成

注这个 .env 服务器启动时会自动加载文件。

运行服务器

Stdio 模式（适用于 Claude 桌面版）

make run-stdio
# or
uv run fastmcp run src/mcp_abstract_api/server.py

HTTP 模式

make run-http
# or
uv run uvicorn mcp_abstract_api.server:app --host 0.0.0.0 --port 8000

# Test the server is running
make test-http

Docker

# Build image locally
make docker-build

# Build and push multi-platform image (amd64 + arm64)
make docker-buildx VERSION=1.0.0

# Run container
make docker-run

Claude 桌面配置

在您的Claude Desktop配置文件中添加：

macOS（苹果电脑操作系统）: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

选项1：HTTP模式（推荐）

首先，启动HTTP服务器：

make run-http

然后将此添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "abstract-api": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp"
      ]
    }
  }
}

好处性能更佳，调试更简便，可远程部署

选项2：标准I/O模式

{
  "mcpServers": {
    "abstract-api": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-abstract-api",
        "run",
        "fastmcp",
        "run",
        "src/mcp_abstract_api/server.py"
      ]
    }
  }
}

注在stdio模式下 .env 项目目录中的文件将被自动加载。使用HTTP模式时，请确保服务器在正确的目录中运行，或者已设置环境变量。

可用的MCP工具

电子邮件验证

• validate_email(email) - 验证电子邮件并检查可送达性

电话号码验证

• validate_phone(phone, country_code?) - 验证电话号码

增值税验证

• validate_vat(vat_number) - 验证欧盟增值税号

IP Intelligence（IP情报）

• geolocate_ip(ip_address, fields?) - 从IP获取位置
• get_ip_info(ip_address) - 获取详细的IP信息
• geolocate_ip_security(ip_address) - 获取IP地理位置并进行安全/威胁分析

时间与地点

• get_timezone(location?, latitude?, longitude?) - 获取时区信息
• convert_timezone(base_location, base_datetime, target_location) - 转换时间
• get_holidays(country, year, month?, day?) - 获取公共假期

财务

• get_exchange_rates(base, target?) - 获取货币汇率
• convert_currency(base, target, amount, date?) - 转换货币

网络与商业

• get_company_info(domain) - 从域名获取公司数据
• scrape_url(url, render_js?) - 抓取网页
• generate_screenshot(url, width?, height?, full_page?) - 网站截图

发展

快速命令

make help          # Show all available commands
make install       # Install dependencies
make dev-install   # Install with dev dependencies
make format        # Format code with ruff
make lint          # Lint code with ruff
make typecheck     # Type check with mypy
make test          # Run tests with pytest
make test-cov      # Run tests with coverage
make test-http     # Test HTTP server is running
make check         # Run all checks (lint + typecheck + test)
make clean         # Clean up artifacts
make all           # Full workflow (clean + install + format + check)

运行测试

# Run all tests
make test

# Run with coverage report
make test-cov

# Run specific test file
uv run pytest tests/test_server.py -v

代码质量

# Format code
make format

# Lint code
make lint

# Fix linting issues automatically
make lint-fix

# Type check
make typecheck

# Run all checks
make check

Docker 命令

# Build local image
make docker-build

# Build and push multi-platform image
make docker-buildx VERSION=1.0.0

# Run container
make docker-run

多平台构建设置 （仅限首次）：

# Create and use a new buildx builder
docker buildx create --name multiplatform --use

# Verify the builder
docker buildx inspect --bootstrap

这个（或“该”） docker-buildx 为两者都构建命令 linux/amd64 和 linux/arm64 架构设计，并直接推送到您的容器注册表。

项目结构

.
├── src/
│   └── mcp_abstract_api/
│       ├── __init__.py
│       ├── server.py          # FastMCP server with tool definitions
│       ├── api_client.py      # Async API client class
│       └── api_models.py      # Pydantic models for type safety
├── tests/
│   ├── __init__.py
│   ├── test_server.py         # Server tool tests
│   └── test_api_client.py     # API client tests
├── pyproject.toml             # Project config with dependencies
├── Makefile                   # Development workflow commands
├── Dockerfile                 # Container deployment
├── pytest.ini                 # Pytest configuration
├── .gitignore                 # Comprehensive ignores
├── .python-version            # Python version (3.13)
└── README.md                  # This file

建筑学

这个项目遵循了 S级MCP服务器架构：

• 关注点分离（或译为：职责分离）API客户端、模型和服务器是相互独立的
• 类型安全优先使用 Pydantic 和 mypy 严格模式进行强类型检查
• 全程异步所有I/O操作使用Async/await
• 错误处理自定义异常、上下文日志记录、优雅失败
• 可测试性支持模拟（mocking）的友好设计，采用依赖注入
• 准备就绪，可用于生产Docker，健康检查，监控支持

要求

• Python 3.13及以上版本
• aiohttp（一个用于异步网络请求的Python库）
• FastAPI
• fastmcp
• pydantic（注：这是一个Python库的名称，直接翻译可能无法准确传达其含义，通常保持原名或根据上下文解释为“一个用于数据验证和设置管理的Python库”）

健康检查与故障排除

服务器在（某个路径）暴露了一个健康检查端点 /health：

curl http://localhost:8000/health
# {"status":"healthy","service":"mcp-abstract-api"}

# Or use the Makefile command
make test-http

HTTP模式故障排除

如果Claude Desktop无法连接到服务器：

1. 检查服务器是否正在运行： make test-http
2. 验证端口确保端口8000未被其他服务占用
3. 检查日志查看服务器输出是否有任何错误
4. 测试MCP端点： curl http://localhost:8000/ 应返回MCP协议信息
5. 验证 .env 文件确保 ABSTRACT_API_KEY 设置在您的 .env 文件

更改端口

要使用不同的端口（例如，9000）：

uv run uvicorn mcp_abstract_api.server:app --host 0.0.0.0 --port 9000

然后更新您的Claude桌面配置以使用 http://localhost:9000/mcp

错误处理

所有API错误都被封装在 AbstractAPIError 与；带着；和……一起

• HTTP状态码
• 错误信息
• 可选的错误详细信息

错误会通过MCP上下文记录下来，以便进行调试。

做出贡献

1. 为仓库创建分支（或“克隆仓库”）
2. 创建一个特性分支
3. 做出你的更改
4. 跑 make check 确保质量
5. 提交一个拉取请求

支持

如需报告问题、提出疑问或贡献代码，请在GitHub上提交一个议题。

许可证

MIT 许可证 - 详见 LICENSE 文件

链接

• 抽象API文档
• FastMCP 文档
• MCP 文档