Smartapi MCP

SmartAPI MCP服务器

为SmartAPI注册表中注册的一个或多个API创建MCP（模型上下文协议）服务器。

概述

SmartAPI MCP服务器支持MCP兼容客户端与SmartAPI注册表中注册的API之间的集成。这允许通过标准化的MCP协议与生物信息学和生命科学API进行无缝发现和交互。

建在 AWS实验室OpenAPI MCP服务器，该项目将MCP支持扩展到SmartAPI注册表中可用的广泛API集合，特别关注生物信息学和生命科学API。

需求

• Python 3.10或更高版本
• SmartAPI注册表的网络访问(https://smart-api.info)
• 依赖关系： awslabs_openapi_mcp_server>=0.2.12

特性

• 🔍 SmartAPI集成：与SmartAPI注册表直接集成，用于API发现
• 🏗️ MCP协议支持：完整的MCP（模型上下文协议）服务器实现
• 🔄 异步架构：采用现代Python异步/等待模式构建，实现高性能
• 📖 OpenAPI验证：自动OpenAPI规范解析和验证
• 🛠️ CLI接口：易于使用的命令行界面，具有多种配置选项
• 🧬 生物信息学焦点：用于生物信息学和生命科学的预先配置的API集合
• 🎯 灵活的配置：支持环境变量、参数和配置文件
• 🚀 多种运输方式：支持stdio和HTTP传输协议
• 🧪 综合测试：具有99%代码覆盖率的完整测试套件

安装

来自PyPI（推荐）

pip install smartapi-mcp

来源

git clone https://github.com/biothings/smartapi-mcp.git
cd smartapi-mcp
pip install -e .

开发安装

git clone https://github.com/biothings/smartapi-mcp.git
cd smartapi-mcp
pip install -e ".[dev]"

与MCP客户端一起使用

与uvx一起使用（推荐）

uvx 是一个在隔离环境中运行Python应用程序的工具。这是为mcp客户端集成运行smartapi-mcp的推荐方法：

安装和基本使用

# Install uvx if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# or with homebrew on macOS
brew install uv

# Run smartapi-mcp with uvx (automatically installs if needed)
uvx smartapi-mcp --api_set biothings_core

# Run with specific version
uvx smartapi-mcp@0.2.0 --api_set biothings_core

# Run with additional arguments
uvx smartapi-mcp --smartapi_id 59dce17363dce279d389100834e43648 --server_name "MyGene MCP Server"

与Claude Desktop一起使用

要在Claude Desktop中使用smartapi-mcp，请将以下配置添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "smartapi-biothings-core": {
      "command": "uvx",
      "args": ["smartapi-mcp", "--api_set", "biothings_core", "--server_name", "BioThings Core APIs"]
    },
    "smartapi-mygene": {
      "command": "uvx",
      "args": ["smartapi-mcp", "--smartapi_id", "59dce17363dce279d389100834e43648", "--server_name", "MyGene.info API"]
    },
    "smartapi-myvariant": {
      "command": "uvx",
      "args": ["smartapi-mcp", "--smartapi_id", "09c8782d9f4027712e65b95424adba79", "--server_name", "MyVariant.info API"]
    }
  }
}

与其他MCP客户端一起使用

对于支持外部MCP服务器的其他MCP客户端，您通常可以通过以下方式进行配置：

• 命令: uvx
• 参数: ["smartapi-mcp", "--api_set", "biothings_core"] （或其他所需的论点）
• 工作目录：可选，可以是任何目录
• 环境变量：可选，请参见 环境变量 部分

MCP服务器配置示例

基础生物信息学设置

{
  "mcpServers": {
    "biothings-core": {
      "command": "uvx",
      "args": ["smartapi-mcp", "--api_set", "biothings_core"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

高级Multi-API设置

{
  "mcpServers": {
    "biothings-comprehensive": {
      "command": "uvx",
      "args": [
        "smartapi-mcp",
        "--smartapi_ids",
        "59dce17363dce279d389100834e43648,09c8782d9f4027712e65b95424adba79,8f08d1446e0bb9c2b323713ce83e2bd3",
        "--server_name",
        "Comprehensive Bioinformatics APIs",
        "--log-level",
        "DEBUG"
      ]
    }
  }
}

开发/测试设置

{
  "mcpServers": {
    "smartapi-dev": {
      "command": "uvx",
      "args": [
        "smartapi-mcp",
        "--api_set",
        "biothings_test",
        "--log-level",
        "DEBUG"
      ],
      "env": {
        "SMARTAPI_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

MCP配置的环境变量

您还可以在MCP客户端配置中使用环境变量：

{
  "mcpServers": {
    "smartapi-configured": {
      "command": "uvx",
      "args": ["smartapi-mcp"],
      "env": {
        "SMARTAPI_API_SET": "biothings_core",
        "SERVER_NAME": "BioThings Core MCP Server",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

MCP客户端的替代安装方法

在虚拟环境中使用pip

如果你不想使用uvx，你可以创建一个专用的虚拟环境：

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

# Install smartapi-mcp
pip install smartapi-mcp

# Test the installation
smartapi-mcp --api_set biothings_core

然后配置MCP客户端以使用可执行文件的完整路径：

{
  "mcpServers": {
    "smartapi-biothings": {
      "command": "/path/to/smartapi-mcp-env/bin/smartapi-mcp",
      "args": ["--api_set", "biothings_core"]
    }
  }
}

使用全系统安装

# Install globally (not recommended for most users)
pip install smartapi-mcp

# Find the installation path
which smartapi-mcp

MCP客户端配置：

{
  "mcpServers": {
    "smartapi-biothings": {
      "command": "smartapi-mcp",
      "args": ["--api_set", "biothings_core"]
    }
  }
}

MCP客户端集成故障排除

服务器未启动

1. 检查uvx安装:

   uvx --version

1. 手动测试服务器:

   uvx smartapi-mcp --api_set biothings_core --log-level DEBUG

1. 检查MCP客户端日志 有关特定错误消息

客户端中未显示工具

1. 验证服务器是否正在运行 已注册工具：

   uvx smartapi-mcp --api_set biothings_core --log-level DEBUG 2>&1 | grep -i "tool"

1. 检查API连接:

   curl -s https://mygene.info/v3/metadata | head -20

1. 请尝试较小的API集 第一：

   uvx smartapi-mcp --smartapi_id 59dce17363dce279d389100834e43648

性能问题

• 使用特定的SmartAPI ID，而不是大型API集
• 仅启用您实际需要的API
• 考虑使用HTTP传输来提高多个并发请求的性能：

  {
    "mcpServers": {
      "smartapi-http": {
        "command": "uvx",
        "args": ["smartapi-mcp", "--api_set", "biothings_core", "--transport", "http", "--port", "8001"]
      }
    }
  }

快速开始

命令行用法

从预定义的API集合开始（推荐）

# Use BioThings core APIs (MyGene, MyVariant, MyChem, MyDisease, MyGeneSet)
smartapi-mcp --api_set biothings_core

# Use all BioThings APIs (with some exclusions)
smartapi-mcp --api_set biothings_all

从特定的SmartAPI ID开始

# Single API
smartapi-mcp --smartapi_id 59dce17363dce279d389100834e43648

# Multiple APIs
smartapi-mcp --smartapi_ids "59dce17363dce279d389100834e43648,09c8782d9f4027712e65b95424adba79"

从HTTP传输（而不是stdio）开始

# HTTP mode on localhost:8000 (default)
smartapi-mcp --api_set biothings_core --transport http

# Custom host and port
smartapi-mcp --api_set biothings_core --transport http --host 0.0.0.0 --port 9000

高级选项

# Custom logging level
smartapi-mcp --api_set biothings_core --log-level DEBUG

# Custom server name
smartapi-mcp --api_set biothings_core --server_name "My Custom MCP Server"

# Query-based API discovery
smartapi-mcp --smartapi_q "tags.name=biothings"

# Exclude specific APIs
smartapi-mcp --api_set biothings_all --smartapi_exclude_ids "api_id_1,api_id_2"

Python API用法

import asyncio
from smartapi_mcp import (
    get_smartapi_ids,
    load_api_spec,
    get_mcp_server,
    get_merged_mcp_server,
    PREDEFINED_API_SETS
)

async def main():
    # Get SmartAPI IDs using a query
    smartapi_ids = await get_smartapi_ids("tags.name=biothings")
    print(f"Found {len(smartapi_ids)} APIs matching the query")

    # Load API specification for a specific SmartAPI
    api_spec = load_api_spec("59dce17363dce279d389100834e43648")  # MyGene.info
    print(f"Loaded API: {api_spec.get('info', {}).get('title', 'Unknown')}")

    # Create MCP server for a single API
    server = await get_mcp_server(
        smartapi_id="59dce17363dce279d389100834e43648",
        server_name="MyGene MCP Server"
    )

    # Create merged MCP server for multiple APIs (recommended approach)
    merged_server = await get_merged_mcp_server(
        api_set="biothings_core",  # Use predefined set
        server_name="BioThings Core MCP Server"
    )

    # Or with specific SmartAPI IDs
    merged_server = await get_merged_mcp_server(
        smartapi_ids=[
            "59dce17363dce279d389100834e43648",  # MyGene.info
            "09c8782d9f4027712e65b95424adba79",  # MyVariant.info
        ],
        server_name="Custom MCP Server"
    )

    # Show available predefined API sets
    print(f"Available API sets: {PREDEFINED_API_SETS}")

    # Run server with stdio transport (default for MCP)
    merged_server.run()

    # Or run with HTTP transport
    # merged_server.run(transport="http", host="localhost", port=8000)

if __name__ == "__main__":
    asyncio.run(main())

API示例

BioThings核心API

当你使用 --api_set biothings_core，您可以访问这些强大的生物信息学API：

1. MyGene.info (59dce17363dce279d389100834e43648)：基因注释和信息
2. MyVariant.info (09c8782d9f4027712e65b95424adba79)：变体注释和信息
3. MyChem.info (8f08d1446e0bb9c2b323713ce83e2bd3)：化学和药物信息
4. MyDisease.info (671b45c0301c8624abbd26ae78449ca2)：疾病信息和关联
5. MyGeneSet.info (85139f4dccfcefa3ac3042372066916d)：收集、分享和保存基因

与MCP客户端一起使用

服务器运行后，MCP兼容的客户端可以发现并使用可用的工具。每个API端点都成为一个可用的MCP工具，具有：

• 工具发现：客户端可以列出所有可用的API终结点
• 参数验证：基于OpenAPI规范的自动参数验证
• 丰富的描述：每个工具都包含API文档中的详细说明
• 错误处理：对无效请求的正确错误响应

配置

服务器支持多种配置方式：

环境变量

# SmartAPI configuration
export SMARTAPI_ID="59dce17363dce279d389100834e43648"
export SMARTAPI_IDS="id1,id2,id3"
export SMARTAPI_Q="tags.name=biothings"
export SMARTAPI_API_SET="biothings_core"
export SMARTAPI_EXCLUDE_IDS="exclude_id1,exclude_id2"

# Server configuration
export SERVER_NAME="My SmartAPI MCP Server"
export TRANSPORT="http"
export HOST="localhost"
export PORT="8000"

# Then run without arguments
smartapi-mcp

命令行参数

所有配置都可以通过命令行参数提供（请参阅上面的快速入门部分）。

预定义的API集

以下预定义的API集合可用：

• biothings_core：核心BioThings API（MyGene、MyVariant、MyChem、MyDisease、MyGeneSet）
• biothings_test：核心API加SemmedDB（可用于测试）
• biothings_all：所有BioThings API（出于稳定性考虑，有一些例外）

配置优先

1. 命令行参数（最高优先级）
2. 环境变量
3. 默认值（最低优先级）

发展

建立开发环境

# Clone the repository
git clone https://github.com/biothings/smartapi-mcp.git
cd smartapi-mcp

# Install development dependencies
pip install -e ".[dev]"

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=smartapi_mcp --cov-report=html

# Run specific test file
pytest tests/test_basic.py

代码质量

# Check and fix linting issues
ruff check .
ruff check . --fix

# Format code
ruff format .

构建包

# Build source and wheel distributions
python -m build

# Check the built package
twine check dist/*

发布到PyPI

手工出版

# Build the package
python -m build

# Upload to Test PyPI (optional)
twine upload --repository testpypi dist/*

# Upload to PyPI
twine upload dist/*

自动发布

此存储库包括用于自动测试和发布的GitHub Actions工作流：

• 测试工作流程 (.github/workflows/test.yml)：对每个推送和拉取请求运行
• 发布工作流 (.github/workflows/publish.yml)：发布时发布到PyPI

要发布新版本，请执行以下操作：

1. 更新中的版本 pyproject.toml 和 smartapi_mcp/__init__.py
2. 提交版本更改
3. 创建并推送一个git标签： git tag v0.2.0 && git push origin v0.2.0
4. 在GitHub上创建新版本
5. 发布工作流将自动构建并上传到PyPI

手动工作流触发器

您还可以手动触发发布工作流以上传到Test-PyPI：

1. 转到GitHub存储库中的Actions选项卡
2. 选择“发布Python包”
3. 点击“运行工作流”
4. 选择“发布到测试PyPI”选项

贡献

我们欢迎捐款！请参阅我们的投稿指南以了解详细信息。

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 进行更改
4. 为您的更改添加测试
5. 确保测试通过(pytest)
6. 提交您的更改(git commit -m 'Add amazing feature')
7. 推到分支(git push origin feature/amazing-feature)
8. 打开拉取请求

故障排除

常见问题

未注册任何工具或资源

WARNING: No tools or resources were registered. This might indicate an issue with the API specification or authentication.

解决方案：这通常发生在以下情况：

• SmartAPI ID无效或API已关闭
• OpenAPI规范存在验证错误
• 网络连接问题

尝试使用已知的工作API集： smartapi-mcp --api_set biothings_core

服务器无法启动

检查你的Python版本：需要Python 3.10+

python --version

验证安装:

pip show smartapi-mcp

HTTP模式连接问题

如果使用HTTP传输模式，客户端无法连接：

• 检查端口是否可用： netstat -an | grep :8000
• 尝试绑定到所有接口： --host 0.0.0.0
• 检查防火墙设置

获取帮助

1. 启用调试日志记录： --log-level DEBUG
2. 检查
3. 联系我们help@biothings.io

许可证

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

相关项目

• SmartAPI注册表 -生物医学和生命科学原料药注册
• 模型上下文协议（MCP） -AI模型工具集成的标准协议
• BioThings API -高性能生物信息学API
• AWS实验室OpenAPI MCP服务器 -基本MCP服务器框架

引用

如果您在研究或应用中使用SmartAPI MCP服务器，请引用：

SmartAPI MCP Server: Bridging Bioinformatics APIs with Model Context Protocol
BioThings Team. (2024). https://github.com/biothings/smartapi-mcp

支持

如有疑问和支持：

• 📖 文档: 自述文件
• 🐛 错误报告:
• 💬 问题:
• 📧 电子邮件: help@biothings.io

______________________________________________________________________

SmartAPI MCP服务器 由开发和维护 BioThings团队 斯克里普斯研究所。