整合
FTIR.fun MCP 伺服器與 REST API
將 FTIR.fun 連接到您的 AI 助手或自動化管道。適用於 Claude/Cursor/Codex 的 MCP 伺服器。用於自訂整合的 REST API。所有方法都提供相同的 130,000+ 參考譜圖和有文獻支援的 AI 解讀。
MCP 伺服器 — Claude、Cursor、Codex
FTIR.fun 的 MCP（模型上下文協定）伺服器已通過審查並正式列於 Anthropic MCP Registry、Smithery 和 MCP.so。它將 FTIR 光譜搜尋、附 DOI 引用文獻的峰位解釋以及材料鑑別，作為可呼叫工具提供給任何相容 MCP 的用戶端。
快速連接
# Claude Desktop / Claude Code
claude mcp add ftirfun https://ftir.fun/mcp
# Cursor
# Add to ~/.cursor/mcp.json:
{"mcpServers": {"ftirfun": {"url": "https://ftir.fun/mcp"}}}
# OpenAI Codex
codex mcp add ftirfun https://ftir.fun/mcp
可用工具
| 工具 | 描述 |
|---|---|
search_ftir_library | 依峰位或上傳檔案搜尋 130K+ 參考譜圖。傳回排名匹配結果，包含 CAS 號碼和相似度分數。 |
search_public_ftir_results | 依關鍵字搜尋社群分享的分析結果。 |
fetch_public_ftir_result | 依 ID 取得特定公開 FTIR 分析結果以進行詳細檢視。 |
伺服器卡片與登錄檔連結
- Server Card (JSON) — 標準 MCP 伺服器探索端點
- Anthropic MCP Registry — 正式列名
- Smithery — 已審查並發布
- MCP.so — 已列出
- PyPI (ftirfun-mcp) — Python 套件
Coze 外掛 — 在豆包內使用
Open Doubao → Plugin Store → search "FTIR" or "红外分析" → tap Add. No configuration needed. Doubao will automatically route infrared-related queries to our spectral search engine.
搜尋關鍵字：紅外分析, FTIR, infrared, 光譜檢索, 物質識別
REST API
資料庫搜尋 API
POST /v1/search
光譜庫搜尋。接受檔案（全光譜比對）或波峰列表（波峰位置比對）。若同時提供，檔案搜尋優先。
驗證
X-API-Key: your-api-key
請求主體
| 欄位 | 類型 | 必填 | 描述 |
|---|---|---|---|
| file_base64 | string | 其中之一 | Base64 編碼的儀器檔案（支援 CSV、SPA、OPUS、SPC、JCAMP-DX 等 15 種以上格式） |
| filename | string | 搭配 file_base64 | 原始檔名（含副檔名，例如 sample.spa） |
| peaks | number[] | 其中之一 | 波峰波數列表（單位 cm⁻¹，例如 [3026, 1601, 1493, 755]） |
| top_k | integer | 否（預設 10） | 回傳結果數量，最多 50 筆 |
| tolerance | integer | 否（預設 8） | 波峰比對容忍度（cm⁻¹），範圍 1–30 |
回應
{
"success": true,
"search_mode": "full_spectrum",
"n_matches": 10,
"matches": [
{
"rank": 1,
"name": "Polystyrene",
"cas": "25086-18-4",
"num": 326,
"similarity": 0.9586
}
],
"file_format": "Thermo SPA",
"n_points": 3601,
"error": null
}
範例 — 檔案上傳
import base64, requests
with open("sample.spa", "rb") as f:
b64 = base64.b64encode(f.read()).decode()
resp = requests.post(
"https://api.ftir.fun/v1/search",
headers={"X-API-Key": "your-key", "Content-Type": "application/json"},
json={"file_base64": b64, "filename": "sample.spa", "top_k": 5},
)
print(resp.json())
範例 — 峰值列表
import requests
resp = requests.post(
"https://api.ftir.fun/v1/search",
headers={"X-API-Key": "your-key", "Content-Type": "application/json"},
json={"peaks": [3082, 3026, 2923, 1601, 1493, 1451, 1028, 906, 755, 699], "top_k": 5},
)
print(resp.json())
現有結果的僅 AI 分析
僅在已有搜尋結果後使用此端點。FTIR.fun 首先讀取或 OCR 提供的報告，提取報告的候選項和樣品峰值表，然後執行下游 KG 和文獻支持的分析。
POST /ftir/analyze_existing_results
報告必須同時包含報告的搜尋結果清單和樣品峰值表。此端點本身不執行光譜資料庫搜尋。
驗證
X-API-Key: your-api-key
請求主體
| 欄位 | 類型 | 必填 | 描述 |
|---|---|---|---|
| report_text | string | 其中之一 | 從現有儀器或資料庫報告複製的純文字。文字必須同時包含報告的結果和樣品峰值表。 |
| report_file_base64 | string | 其中之一 | Base64 編碼的報告檔案。支援的格式：PDF、DOC、DOCX、TXT、CSV、PNG、JPG、JPEG、WEBP、GIF、BMP、TIF、TIFF。 |
| report_filename | string | 使用 report_file_base64 | 原始報告檔案名稱（包含副檔名，例如 report.pdf 或 report.docx）。 |
| user_background_text | string | 否 | 可選的樣品背景。這僅被視為軟性上下文，而非證據。 |
嚴格的輸入邊界
- 必要元素 1：至少一個報告的搜尋結果候選項，例如 Top1 命中或 Top15 清單
- 必要元素 2：同一報告中以 cm-1 為單位的樣品峰值清單或峰值表
- 如果缺少任一元素，端點將返回 HTTP 422 且不生成分析報告
成功回應
{
"success": true,
"analysis_mode": "ai_only_existing_results",
"message": "AI-only analysis completed from the supplied existing results report.",
"input_requirements": {
"service_boundary": "AI-only analysis starts after a search result already exists.",
"required_inputs": [
"At least one reported search result candidate (Top1 or Top15).",
"The sample peak table or peak list in cm-1."
]
},
"missing_requirements": [],
"missing_requirement_messages": [],
"extracted_report": {
"source_kind": "pdf",
"used_ocr": true,
"peak_values_cm1": [1736, 1601, 1241],
"library_candidates": [
{"rank": 1, "name": "Polyethylene terephthalate", "cas_number": "25038-59-9", "raw_score_text": "856/1000", "normalized_similarity": 0.856}
]
},
"summary": "Reported library results rank Polyethylene terephthalate first.",
"report_view": {},
"final_decision": {},
"direct_evidence": {},
"related_literature": {}
}
缺少輸入的回應
{
"detail": {
"success": false,
"analysis_mode": "ai_only_existing_results",
"error": "missing_required_report_elements",
"message": "AI-only analysis requires both reported library results and a sample peak table.",
"missing_requirements": ["sample_peak_table"],
"missing_requirement_messages": [
"Missing sample peak table. Provide the sample peak list or peak table in cm-1 from the same report."
],
"input_requirements": {
"failure_behavior": "If either the reported result list or the sample peak table is missing, the service stops and returns a 422 response."
},
"extracted_report": {
"report_has_library_results": true,
"report_has_peak_table": false
}
}
}
範例 — 現有報告文字
import requests
report_text = """
Sample: PET fragment
Top1: Polyethylene terephthalate Score: 856/1000
Top2: Polyester resin Score: 801/1000
Peak table (cm-1): 3435, 2932, 1715, 1409, 1241, 1093, 1017, 872, 722
"""
resp = requests.post(
"https://api.ftir.fun/ftir/analyze_existing_results",
headers={"X-API-Key": "your-key", "Content-Type": "application/json"},
json={"report_text": report_text, "user_background_text": "consumer packaging fragment"},
)
print(resp.json())
範例 — 現有報告檔案
import base64, requests
with open("instrument-report.pdf", "rb") as f:
b64 = base64.b64encode(f.read()).decode()
resp = requests.post(
"https://api.ftir.fun/ftir/analyze_existing_results",
headers={"X-API-Key": "your-key", "Content-Type": "application/json"},
json={
"report_file_base64": b64,
"report_filename": "instrument-report.pdf",
"user_background_text": "suspected packaging adhesive",
},
)
print(resp.json())
錯誤代碼
| HTTP 狀態 | 意義 |
|---|---|
| 200 | 成功 |
| 401 | 缺少或無效的 API 金鑰 |
| 422 | 無效的請求主體、不支援的報告格式或缺少必要的報告元素 |
| 500 | 伺服器端錯誤 |