Agent 接入

先選擇執行環境

本站以唯讀授權提供目錄查詢及已驗證的私人 COS 報告下載。可攜式 Node 版本另提供本機下載及私人閱讀紀錄。

從本機程序接入

需要 Node.js 22 或更新版本。在可攜式原始碼套件根目錄執行：

npm run build
npm start

網站預設位於 http://127.0.0.1:3000，MCP 位於 http://127.0.0.1:3000/mcp。未設定 API key 時，HTTP 只提供五個目錄工具，私人研究庫路由停用。

stdio 用戶端設定

把以下設定加入支援 MCP 的用戶端。將兩個絕對路徑換成你自己的位置。程序直接讀取應用程式內的 public/catalog.json，不依賴用戶端目前工作目錄。

{
  "mcpServers": {
    "tiansight": {
      "command": "node",
      "args": ["/absolute/path/to/tiansight/server/index.mjs", "--stdio"],
      "env": {
        "TIANSIGHT_LIBRARY_DIR": "/absolute/path/to/my-private-research"
      }
    }
  }
}

stdio 使用逐行 JSON-RPC；標準輸出只傳協定 JSON，作業錯誤寫入標準錯誤。stdio 可使用全部八個工具，不需要 HTTP API key。

啟用 HTTP 私人研究庫

在環境變數設定足夠長的隨機密鑰，並指定私人保存目錄：

export MCP_API_KEY='replace-with-a-long-random-secret'
export TIANSIGHT_LIBRARY_DIR='./library/private'
npm start

設定密鑰後，所有 /api/… 與 /mcp 請求，包括目錄讀取，都必須附上 Authorization: Bearer <key>。靜態頁面及 /health 仍公開。密鑰由 API 用戶端提供，不要寫進公開網站、原始碼或網址。

npm run build
docker build -t tiansight-local .
docker volume create tiansight-library
docker run --rm --name tiansight-local \
  -p 127.0.0.1:3000:3000 \
  -e MCP_API_KEY="$MCP_API_KEY" \
  -e TIANSIGHT_ALLOWED_ORIGINS='http://127.0.0.1:3000,http://localhost:3000' \
  -v tiansight-library:/app/library/private \
  tiansight-local

以穩定 ID 串起研究工作

先搜尋、讀取記錄，再核對歷期與取得條件。工具接受目錄中的 ID；不接受任意網址、檔案路徑或文件匯入。

線上與本機共用 · 五個唯讀工具

limit 預設 20，整數 1–100；offset 預設 0，整數 0–100000。downloadMode：direct、landing、registration、subscription。未知參數、錯誤值及無效 ID 會回傳錯誤。

本站 COS 歸檔 · 唯讀授權

呼叫 get_archived_report，參數為 {"reportId":"nra-whats-hot-2025"}。已歸檔報告回傳五分鐘有效的 HTTPS URL、SHA-256、位元組數與發布機構依據。下載後請核對雜湊；連結到期後重新呼叫工具。未歸檔項目回傳 not_archived 及官方入口。工具不接受自訂物件路徑或存儲桶。唯讀 token 只可呼叫五個目錄工具及此歸檔工具。

本機專用 · 三個私人研究庫工具

標籤最多 30 個不重複字串，每個最多 80 字元；筆記最多 10000 字元，空字串清除舊筆記。archived 是閱讀狀態，不刪除檔案。本頁提供接入文件；私人資料透過工具或 API 管理。

單次請求，完整回應

相對端點為 /mcp；在可攜式 Node 預設環境中，完整網址為 http://127.0.0.1:3000/mcp。本站使用管理員授予的唯讀 Bearer token；本機使用另行設定的 API key。

實作支援 2026-07-28 無狀態 MCP：server/discover、tools/list、tools/call 與 ping。每次回傳單一 JSON，不建立協定 session 或常駐 SSE；GET 與 DELETE /mcp 回傳 405。

curl http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: search_reports' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_reports","arguments":{"q":"food consumer","limit":10},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

相容 2025 用戶端

2025-11-25 用戶端可依序呼叫 initialize、notifications/initialized，再使用相同工具。初始化需提供 protocolVersion、clientInfo: {name, version} 與 capabilities: {}。後續 HTTP 請求需帶 MCP-Protocol-Version: 2025-11-25；stdio 會記住程序內的舊版初始化狀態。

未宣告資源、提示、訂閱、背景任務或 elicitation。實際可用工具以當次 tools/list 為準。

可攜式 REST 入口

私人工具路由僅存在於 Node 執行環境，且要求密鑰。POST 使用 Content-Type: application/json，上限 256 KiB。搜尋參數不可重複，未知鍵會拒絕處理。

保存檔案，也保存依據

套件與網站不附報告全文檔案。下載工具僅為已建檔、免費且可直接下載的 PDF、CSV 或 JSON 取得實際檔案。落地頁、登記與訂閱內容回傳 manual_action_required 及官方入口，需自行完成官方存取流程。

預設私人目錄為 ./library/private，可用 TIANSIGHT_LIBRARY_DIR 變更。內容保存為 files/<sha256>.<format>，以 manifest.json 記錄來源、官方依據、原始及最終網址、時間、格式、大小、雜湊與閱讀資料。同內容以 SHA-256 去重，各報告仍保留各自出處。

寫入以暫存檔及原子更名完成，一個目錄只由一個程序管理。請自行備份私人目錄；系統不會自動刪除下載檔或封存紀錄。

讀取內容之前，確認索引口徑

目前目錄包含 55 個來源記錄、70 份具體報告版本。70 是實際建檔版本數，不是完整出版史或可下載檔案數。一個來源入口可包含多份尚未逐一建檔的報告；歷期查詢只列出本索引已收錄的版本。

搜尋範圍為標題、摘要、主題、關鍵字與發布機構等中繼資料。所有以空白／標點分隔的搜尋 token 都必須匹配，允許分別匹配不同欄位。標題優先排序；處理大小寫、全半形與實用繁簡字對應，但沒有全文擷取、OCR、語意向量或自動翻譯搜尋。下載檔案後不會自動建立全文索引。

year 是報告版本年份，可能與資料涵蓋期間不同。正式引用請保留發布機構、版本、資料期間、頁碼／表號、原始網址與讀取日期。開放閱讀不代表全文轉載授權。

目前不提供背景下載佇列、排程更新、使用者帳號、發布機構登入或跨裝置同步。瀏覽器研究清單與可攜式私人檔案／閱讀紀錄分開保存。

官方協定參考

• MCP 2026-07-28 specification ↗
• Server discovery ↗
• Tools ↗
• 2025-11-25 lifecycle ↗