icsc-ava-upload-toolkit

ICSC Ava Upload Toolkit

完整的檔案上傳工具套件，包含 MCP Server 和 Mock File Service，支援工具鏈設計，專為 LibreChat 系統設計。

功能

MCP Server (icsc-ava-upload-mcp-server)

• download_and_upload: [CHAINING TOOL] 接收來自上游工具的暫存 URL，下載檔案並上傳到 LibreChat 後端系統

Mock File Service (mock-file-service)

• FastAPI 模擬服務: 模擬 Node.js Fastify 的 AVA File Service
• 檔案上傳/下載: 提供完整的檔案管理 API
• 多種儲存類型: 支援 chat、crawler、doc、logs 等不同類型的檔案儲存

安裝

使用 uv 安裝

# 安裝專案依賴
uv sync

# 或者以開發模式安裝
uv pip install -e .

使用 uvx 直接運行

MCP Server

# 從本地專案運行 MCP Server (STDIO 模式)
uvx --from . icsc-ava-upload-server stdio

# MCP Server (HTTP 模式) - 可指定 host 和 port
uvx --from . icsc-ava-upload-server http 127.0.0.1 8001

# 使用簡短命令
uvx --from . icsc-ava-mcp stdio

Mock File Service

# 從本地專案運行 Mock File Service - 可指定 host 和 port
uvx --from . mock-file-service 127.0.0.1 8090

# 使用簡短命令
uvx --from . icsc-ava-mock-service 127.0.0.1 8090

# 開發模式 (支援熱重載)
uvx --from . mock-file-service 127.0.0.1 8090 --reload

運行模式

MCP Server 運行模式

STDIO 模式

適用於本地 MCP Client 連接：

# 使用 uv run
uv run python -m icsc_ava_upload_mcp_server.server stdio

# 或使用安裝後的命令
uv run icsc-ava-upload-server stdio

Streamable HTTP 模式

適用於遠端 MCP Client 連接：

# 使用 uv run (預設 127.0.0.1:8001)
uv run python -m icsc_ava_upload_mcp_server.server http

# 指定 host 和 port
uv run python -m icsc_ava_upload_mcp_server.server http 0.0.0.0 9000

# 或使用安裝後的命令
uv run icsc-ava-upload-server http 127.0.0.1 8001

Mock File Service 運行模式

# 使用 uv run (預設 127.0.0.1:8090)
uv run python -m mock_file_service.server

# 指定 host 和 port
uv run python -m mock_file_service.server 0.0.0.0 9000

# 開發模式 (熱重載)
uv run python -m mock_file_service.server 127.0.0.1 8090 --reload

# 或使用安裝後的命令
uv run mock-file-service 127.0.0.1 8090

同時運行兩個服務

方法一：使用快速啟動腳本（推薦）

# 一鍵啟動兩個服務
uv run icsc-ava-start

# 或使用 uvx
uvx --from . icsc-ava-start

方法二：手動啟動

# 終端機 1: 啟動 Mock File Service
uv run mock-file-service 127.0.0.1 8090

# 終端機 2: 啟動 MCP Server
uv run icsc-ava-upload-server http 127.0.0.1 8001

HTTP 模式預設監聽：

• MCP Server: http://127.0.0.1:8001/mcp
• Mock File Service: http://127.0.0.1:8090

MCP Client 設定範例

Claude Desktop (stdio 模式)

在 claude_desktop_config.json 中加入：

{
  "mcpServers": {
    "icsc-ava-upload": {
      "command": "uvx",
      "args": ["--from", "D:\\project\\icsc-file-uploader", "icsc-ava-upload-server", "stdio"]
    }
  }
}

HTTP 模式連接

啟動 HTTP 伺服器後，MCP Client 可連接到：

• URL: http://127.0.0.1:8001/mcp

開發

VSCode 啟動設定

專案已包含 .vscode/launch.json，提供兩種除錯模式：

• MCP Server (STDIO): 以 stdio 模式啟動
• MCP Server (HTTP): 以 streamable-http 模式啟動

發佈

發佈到官方 PyPI

• 更新版本號：

  # 更新 pyproject.toml 中的版本號
  # 確保版本號遵循語意化版本控制 (Semantic Versioning)
  

• 構建套件：

  # 使用 uv 構建套件
  uv build
  
  # 或使用傳統的 setuptools
  python -m build
  

• 上傳到 PyPI：

  # 上傳到官方 PyPI
  uv publish --publish-url https://upload.pypi.org/legacy/
  
  # 或使用 twine
  python -m twine upload dist/*
  

• 驗證發佈：

  # 檢查套件是否成功發佈
  pip install icsc-ava-upload-toolkit
  
  # 或使用 uv
  uv add icsc-ava-upload-toolkit
  

發佈到測試 PyPI

如需先測試發佈流程：

# 上傳到測試 PyPI
uv publish --publish-url https://test.pypi.org/legacy/

# 從測試 PyPI 安裝
pip install --index-url https://test.pypi.org/simple/ icsc-ava-upload-toolkit

Git 標籤管理

發佈時建議建立 Git 標籤：

# 建立標籤
git tag v1.0.0

# 推送標籤到遠端
git push origin v1.0.0

發佈檢查清單

• 版本號已更新
• CHANGELOG.md 已更新
• 所有測試通過
• 文檔已更新
• 構建成功
• 測試 PyPI 驗證通過
• 正式發佈到 PyPI

授權

MIT License