Invade.tw MCP 伺服器 - AI 語言完整性工具 | Doeshing

┌──────────────────┐
│  Claude Desktop  │
│                  │
│  使用者輸入：      │
│  "數據庫管理"      │
└────────┬─────────┘
         │ MCP 請求
         ▼
┌──────────────────┐
│   MCP 伺服器      │
│   (invade-tw)    │
│                  │
│ ┌──────────────┐ │
│ │ check_vocab  │ │──▶ YAML 資料庫
│ └──────────────┘ │
│ ┌──────────────┐ │
│ │ search_items │ │──▶ 實體資料庫
│ └──────────────┘ │
└────────┬─────────┘
         │ MCP 回應
         ▼
┌──────────────────┐
│  Claude Desktop  │
│                  │
│  建議：           │
│  "資料庫管理" ✓    │
└──────────────────┘

靜態網站產生

這個專案包含一個精密的靜態網站產生器（cmd/build/），能將 YAML 資料庫檔案轉換成 invade.tw 網站：

建置流程：

YAML 檔案 → 編譯器 → 實體模型 → 檢視產生器 → HTML/CSS/JS
            ↓
       序列化器 → JSON（用於客戶端搜尋）
            ↓
       繪圖工具 → 封面圖片（SVG/PNG）

關鍵元件：

compiler/：解析 YAML 檔案並建立記憶體內資料庫
entity/：定義符合 YAML 架構的資料模型
view/：為每個項目、詞彙、分類和搜尋介面產生 HTML 頁面
draw/：建立包含項目/詞彙資訊的封面圖片
serialize/：將資料匯出為 JSON，提供瀏覽器搜尋功能

這種雙重用途的架構讓同一個資料來源能同時支援 AI 整合（透過 MCP）和人類存取（透過靜態網站）。

核心功能

MCP 伺服器提供 7 個工具，分為兩大類：

詞彙工具（4 個工具）

1. check_vocab - 主動詞彙驗證

專為大型語言模型設計的特殊工具，讓 AI 在輸出前自我檢查詞彙。回傳詞語是否存在於入侵詞彙資料庫中，若找到則提供替代方案。

2. search_vocabs - 搜尋詞彙資料庫

在 374 個詞彙項目中進行關鍵字搜尋
依分類篩選（19 個分類：科技、網路、遊戲等）
可設定結果數量上限
回傳完整定義和例句

3. get_vocab - 取得特定詞語的詳細資訊

包含注音（注音符號）
完整說明和棄用原因
正確/錯誤用法範例
不當內容警告（如適用）

4. list_vocab_categories - 列出所有 19 個詞彙分類

回傳完整分類列表
協助使用者了解可用的篩選條件

實體工具（3 個工具）

5. search_items - 搜尋實體資料庫

查詢 397 個項目（公司、品牌、軟體、遊戲、人物）
依分類篩選（24 個分類：網路、軟體、遊戲等）
依類型篩選（7 種類型：公司、人物、軟體等）
依所有者篩選（4 種類型：中國、台灣、外國、香港）
依入侵程度篩選（4 種類型：操控、合作、資助、支援）

6. get_item - 取得特定實體的詳細資訊

包含 [[wiki 風格]] 交叉參照的完整說明
母公司關係
多個名稱和別名
網站和背景資訊
詳細的入侵時間軸，含年份和說明

7. list_item_categories - 列出所有 24 個項目分類

回傳完整分類列表
協助使用者了解可用的篩選條件

即時整合

無縫 AI 工作流程：

使用者撰寫 → MCP 檢查詞彙 → Claude 建議替代方案
                           ↓
                  無需切換工具！

實作重點

資料結構設計

詞彙模型：

type Vocabulary struct {
    Word        string    `yaml:"word"`
    Bopomofo    string    `yaml:"bopomofo"`
    Category    string    `yaml:"category"`
    Explicit    string    `yaml:"explicit"`      // LANGUAGE、SEXUAL
    Description string    `yaml:"description"`
    Deprecation string    `yaml:"deprecation"`
    Notice      string    `yaml:"notice"`
    Examples    []Example `yaml:"examples"`
}
 
type Example struct {
    Words       []string `yaml:"words"`         // 正確替代方案
    Description string   `yaml:"description"`
    Correct     string   `yaml:"correct"`       // 用法範例
    Incorrect   string   `yaml:"incorrect"`     // 反例
}

實體模型：

type Item struct {
    Code        string        `yaml:"code"`
    ParentCode  string        `yaml:"parent_code"`
    Name        string        `yaml:"name"`
    NameAlias   string        `yaml:"name_alias"`
    NameOthers  []string      `yaml:"name_others"`
    Category    string        `yaml:"category"`      // 24 個分類
    Type        string        `yaml:"type"`          // 7 種類型
    Owner       string        `yaml:"owner"`         // 4 種所有者類型
    Website     string        `yaml:"website"`
    Description string        `yaml:"description"`
    Information []Information `yaml:"information"`
}
 
type Information struct {
    Invasion    string `yaml:"invasion"`    // 操控、合作、資助、支援
    Year        string `yaml:"year"`
    Description string `yaml:"description"`
}

YAML 資料載入

MCP 伺服器在啟動時會載入 database/vocabs/（374 個檔案）和 database/items/（397 個檔案）中的所有 YAML 檔案，建立記憶體內資料結構以進行快速查詢。

為什麼選擇 YAML？

具備可讀性，方便社群貢獻
適合 Git 版本控制的差異比對
容易進行架構驗證
資料更新時無需建置步驟

MCP 工具註冊

伺服器在啟動時使用 mcp-go 函式庫註冊所有 7 個工具，並依照 MCP 協定要求透過標準輸入輸出（stdio）進行通訊。

測試與品質保證

手動測試方式

MCP 伺服器透過以下方式進行測試：

1. Claude Desktop 整合測試：

Claude Code 使用 MCP

在 Claude Desktop 設定中安裝伺服器
透過自然語言提示測試所有 7 個工具
驗證 YAML 資料庫的回應正確性
檢查邊界情況處理（缺少詞語、無效分類）

2. MCP 檢查工具：

使用官方 MCP 檢查工具驗證協定符合性
驗證工具架構和參數驗證
測試 stdio 通訊通道
確認 JSON-RPC 訊息格式正確

3. 資料庫驗證：

所有 771 個檔案（397 個項目 + 374 個詞彙）的 YAML 語法驗證
必填欄位的架構符合性檢查
[[wiki-連結]] 的交叉參照驗證
分類/類型列舉的一致性

效能特性

觀察到的執行期行為（大約值，依環境而定）：

伺服器初始化：快速（在現代硬體上約 50ms）
詞彙查詢：幾乎即時（記憶體內雜湊表）
實體搜尋：關鍵字比對快速（線性掃描約 400 個項目）
記憶體佔用：輕量（載入完整資料庫約 10MB）

註：這些是開發過程中觀察到的特性，非正式效能評測。

部署

Claude Desktop 整合

設定檔（claude_desktop_config.json）：

{
  "mcpServers": {
    "invade-tw": {
      "command": "/path/to/invade-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

使用範例：

使用者可以要求 Claude Desktop 檢查文字中的入侵詞彙。Claude 會自動呼叫 MCP 伺服器工具來識別有問題的詞語，並建議台灣華語替代方案。

社群影響

開放原始碼貢獻

Pull Request #15 -「實作 MCP 伺服器」：

合併時間：2024 年 10 月 18 日
新增具有 7 個工具的 MCP 伺服器實作
核心檔案：cmd/mcp-server/main.go、data.go、tools.go
讓 AI 助理能夠查詢 invade.tw 資料庫

程式碼審查回饋：

「MCP 伺服器將有助於即將推出的社群平台」 — YamiOdymel，專案維護者

資料庫成長

社群驅動：

374 個詞彙項目（截至 2024 年 10 月）
397 個實體記錄（截至 2024 年 10 月）
核心貢獻者積極維護
繁體中文為主要語言，附英文別名

技術文件

儲存庫結構：

invade/
├── cmd/
│   ├── build/              # 靜態網站產生器
│   │   ├── compiler/       # YAML → Go 結構編譯
│   │   ├── entity/         # 資料模型（item.go、vocab.go）
│   │   ├── view/           # HTML 頁面產生
│   │   ├── draw/           # 封面圖片產生
│   │   └── serialize/      # JSON 序列化（用於搜尋）
│   └── mcp-server/
│       ├── main.go         # MCP 伺服器進入點
│       ├── data.go         # 資料庫載入邏輯
│       └── tools.go        # MCP 工具實作
├── database/
│   ├── items/              # 397 個實體 YAML 檔案
│   ├── vocabs/             # 374 個詞彙 YAML 檔案
│   ├── items_logos/        # 標誌圖片
│   └── news/               # 新聞項目
├── docs/                   # 產生的靜態網站
└── go.mod

API 參考：

關鍵學習

技術洞察：

MCP 協定為 AI 工具整合提供有效的抽象層
YAML 兼顧人工編輯和機器處理
Go 產生無需執行期相依性的靜態二進位檔
標準輸入輸出通訊適合本地 MCP 伺服器

開放原始碼協作：

清楚的 PR 說明協助維護者理解貢獻
良好的文件支援專案採用
社群驅動的資料庫受益於易存取的資料格式

結論

invade.tw MCP 伺服器展示了現代 AI 助理如何透過標準化協定強化專業知識庫。透過啟用即時詞彙檢查和實體資訊查詢，這個工具在保持創作流程的同時維護語言完整性。

這項貢獻讓語言意識在 AI 輔助工作流程中無縫存取，支援台灣的語言多樣性，服務社群中的寫作者、開發者和內容創作者。

專案狀態： 已合併並活躍 | 檢視 Pull Request #15

授權： MIT（程式碼）+ CC0（資料）| 貢獻者： @KoukeNeko + invade.tw 社群

完成時間： 2024 年 10 月 | 貢獻於台灣語言意識倡議