OPTIMADE MCP SERVER

这是一个通过Model Context Protocol (MCP)协议查询兼容Optimade材料数据库的工具，支持完全可配置的自定义过滤器预设和提供者端点。

---

🎯 概述

此工具可通过MCP协议在多个OPTIMADE数据库（如Materials Project、Materials Cloud、COD）之间进行结构化数据查询。主要功能包括：

1. 通过uvx、cline轻松部署
2. 支持以自然语言与客户端交互，使大型语言模型能够生成OPTIMADE查询过滤器。
3. OPTIMADE返回的JSON将被本地保存，并在交互过程中生成摘要。

注意：查询需要两个参数。一个是OPTIMADE查询过滤器，另一个是要查询的数据库。

---

✨ 功能

• MCP资源 模型按需读取：
  • optimade://docs/filters – 过滤器语法规则及示例（Markdown）
  • optimade://spec/queryable_props – 白名单：标记为“必须是可查询属性”的字段（JSON）
  • optimade://docs/providers – 默认提供者URL（JSON，由配置生成）
  • optimade://docs/filter_presets – 命名过滤器片段（JSON）
  • optimade://prompts/ask_for_provider – 系统提示以指导URL选择及检查（文本）
  • optimade://results/<uuid> – 动态：过去查询的完整JSON
• 工具
  • lint_filter(filter) → "ok" / "warn: …" / "syntax error: …"
    （警告 = 不在白名单但允许；语法错误 = 阻止）
  • query_optimade(filter, baseUrls?) → 预览（前5个）+ 完整JSON资源链接
  • list_providers() → 发现全球公共OPTIMADE端点
• 提供者回退
  1. 用户提供的baseUrls → 2) 配置默认值 → 3) 回退单镜像（https://optimade.fly.dev）
• 代理支持 通过.env（HTTP_PROXY，HTTPS_PROXY）。

---

🧩 大型语言模型可以读取的资源（资源）

URI	类型	目的
optimade://docs/filters	text/markdown	完整语法规则及示例
optimade://spec/queryable_props	application/json	白名单：标记为“必须是可查询属性”的字段
optimade://docs/providers	application/json	默认提供者URL（来自配置）
optimade://docs/filter_presets	application/json	命名过滤器片段供参考
optimade://prompts/ask_for_provider	text/plain	系统提示以指导URL选择及检查
optimade://results/<uuid>	application/json	动态：过去查询的完整JSON

重要：资源不会自动注入。您的MCP客户端必须调用resources/read（或您配置启动/工作流以读取它们）。

---

⚙️ 安装与使用

✅ 推荐通过uv安装

1. 安装工具：

uv pip install optimade-mcp-server

2. 在cline或任何MCP兼容的启动器中，按照以下方式配置工具：

{
  "mcpServers": {
    "optimade_mcp_server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "optimade-mcp-server"
      ]
    }
  }
}

---

🌐 代理支持（可选）

如果您需要使用VPN或代理，请在项目根目录创建一个.env文件：

HTTP_PROXY=http://127.0.0.1:<your-port>
HTTPS_PROXY=http://127.0.0.1:<your-port>

如果您不需要代理，可以在源代码中注释掉或移除代理设置。

---

🪪 许可证

本项目采用MIT许可证。详情见LICENSE。

---

🙋 常见问题解答

Q: 资源会自动注入到模型上下文中吗？
A: 不会。客户端必须调用resources/read（或配置启动/工作流步骤）。如果省略baseUrls，服务器会自动应用提供者回退。

Q: 我可以使用非白名单字段吗？
A: 可以。lint_filter返回warn: band_gap。模型应显示警告并询问您确认后再进行查询。

Q: 如何导出完整结果？
A: 服务器始终会在optimade://results/<uuid>下保存完整JSON。