OmniRoute/docs/i18n/ms/docs/frameworks/MCP-SERVER.md

OmniRoute MCP Server Documentation (Bahasa Melayu)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Pelayan Model Context Protocol dengan 110 alat merangkumi operasi penghalaan, cache, pemampatan, memori, kemahiran, proksi, pool, Radar dan sumber konteks.

Sumber rujukan utama: open-sse/mcp-server/server.ts mengira 110 alat unik dengan countUniqueMcpTools(): 45 takrif kanonik (termasuk enam alat kitar hayat CCR, trio agent-skills, omniroute_radar_catalog dan omniroute_x_search), serta memori (3), kemahiran (4), kemahiran GitHub (3), pool (6), gamifikasi (8), pemalam (8), Notion (6), Obsidian (22), korpus setempat (3) dan dua alat pemampatan RTK sahaja.

Pemasangan

OmniRoute MCP terbina dalam. Mulakannya dengan:

omniroute --mcp

Atau melalui pengangkutan open-sse:

# Pengangkutan HTTP boleh distrim (port 20130)
omniroute --dev  # MCP bermula secara automatik pada titik akhir /mcp

Pengangkutan HTTP (sse / streamable-http, disediakan dalam proses oleh pelayan papan pemuka) dilumpuhkan secara lalai dan sebelum ini hanya boleh ditogol daripada halaman /dashboard/mcp. Mulai v3.8.51, CLI mempunyai keupayaan yang setara:

omniroute mcp status                                  # didayakan/dalam talian, pengangkutan, bilangan alat
omniroute mcp enable [--transport stdio|sse|streamable-http]
omniroute mcp disable
omniroute mcp restart                                 # menetapkan semula sesi sse/streamable-http yang aktif

mcp enable/mcp disable menghantar PATCH kepada tetapan mcpEnabled yang sama (dan secara pilihan mcpTransport) yang ditogol oleh papan pemuka melalui /api/settings. mcp restart memanggil POST /api/mcp/restart: ia menamatkan sesi sse/streamable-http yang aktif supaya permintaan seterusnya dimulakan semula dengan bersih, mengembalikan 409 jika MCP dilumpuhkan dan 501 untuk pengangkutan stdio (klien stdio memiliki subproses mereka sendiri — tiada pemegang dalam proses untuk dimulakan semula).

Pengangkutan

Pelayan MCP menyediakan tiga pengangkutan, semuanya disokong oleh kilang createMcpServer() yang sama:

Pengangkutan	Lokasi	Masa untuk digunakan
stdio	open-sse/mcp-server/server.ts	Penyepaduan IDE (Claude Desktop, Cursor dan sebagainya)
sse	POST/GET /api/mcp/sse melalui httpTransport	Klien pelayar/ejen yang memerlukan strim peristiwa
streamable-http	POST/GET/DELETE /api/mcp/stream	Klien HTTP berbilang sesi (pengepala mcp-session-id)

Pengangkutan HTTP yang aktif (sse atau streamable-http) dipilih melalui tetapan mcpTransport. Penukaran pengangkutan akan menutup sesi sedia ada pada pengangkutan yang lain.

Akses jauh (pintasan skop manage)

/api/mcp/* berada dalam peringkat LOCAL_ONLY (src/server/authz/routeGuard.ts) — secara lalai, hanya hos gelung balik (localhost, 127.0.0.1, ::1) boleh mencapainya. Sejak v3.8.2, klien bukan gelung balik boleh bersambung jika mereka mengemukakan Authorization: Bearer <api-key> dengan kunci yang mempunyai skop manage. Ini ialah satu-satunya cara untuk mencapai pelayan MCP jauh melalui terowong, proksi songsang atau nama hos awam.

# Berikan skop manage: buka halaman API Keys pada papan pemuka dan togol
# "Management Access" pada kunci tersebut, atau POST scopes:["manage"] semasa mencipta.

# Kemudian sambung daripada klien MCP jauh:
curl -i \
  -H "Host: your-public-host.example" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"0"}}}' \
  https://your-public-host.example/api/mcp/stream

Kunci tanpa skop manage (atau tanpa Bearer) mengembalikan 403 LOCAL_ONLY. Awalan setara /api/cli-tools/runtime/* sengaja TIDAK boleh dipintas — lihat Peringkat Pengawal Laluan — pengecualian skop manage.

Konfigurasi IDE

Lihat Konfigurasi Klien MCP untuk penyediaan Claude Desktop, Cursor, Cline dan klien MCP yang serasi.

---

Alat Penting (14) — Fasa 1

Alat	Skop	Penerangan
omniroute_get_health	read:health	Masa operasi, memori, pemutus litar, had kadar, statistik cache
omniroute_list_combos	read:combos	Semua kombo yang dikonfigurasikan berserta strategi (metrik pilihan)
omniroute_get_combo_metrics	read:combos	Metrik prestasi untuk kombo tertentu
omniroute_switch_combo	write:combos	Aktifkan atau nyahaktifkan kombo
omniroute_create_combo	write:combos	Cipta kombo yang disahkan melalui API kombo sedia ada
omniroute_check_quota	read:quota	Kuota digunakan/jumlah, peratus yang berbaki, masa tetapan semula, kesihatan token
omniroute_route_request	execute:completions	Hantar pelengkapan sembang melalui penghalaan OmniRoute
omniroute_cost_report	read:usage	Laporan kos mengikut tempoh (sesi/hari/minggu/bulan)
omniroute_list_models_catalog	read:models	Katalog model lengkap berserta keupayaan, status dan harga
omniroute_radar_catalog	read:radar	Katalog Radar bertandatangan setempat; penapis penyedia/keluarga pilihan
omniroute_tool_search	read:tools	Temui alat daripada katalog MCP yang didaftarkan
omniroute_web_search	execute:search	Carian web melalui penyedia carian yang dikonfigurasikan. Bukan X/Twitter.
omniroute_x_search	execute:search	Cari X melalui xAI/SuperGrok, atau pilih xquik-search untuk hasil API Xquik. Memerlukan kelayakan untuk bahagian belakang yang dipilih.
omniroute_web_fetch	execute:search	Ambil kandungan web melalui penyedia pengambilan yang dikonfigurasikan

Alat Lanjutan (11) — Fasa 2

Alat	Skop	Penerangan
omniroute_simulate_route	read:health, read:combos	Simulasi penghalaan percubaan tanpa pelaksanaan dengan pepohon sandaran
omniroute_set_budget_guard	write:budget	Bajet sesi dengan tindakan penurunan taraf/sekatan/amaran
omniroute_set_routing_strategy	write:combos	Kemas kini strategi gabungan semasa masa jalan (keutamaan/berwajaran/automatik/dll.)
omniroute_set_resilience_profile	write:resilience	Gunakan pratetap daya tahan aggressive / balanced / conservative
omniroute_test_combo	execute:completions, read:combos	Ujian langsung bagi setiap penyedia dalam gabungan menggunakan panggilan huluan sebenar
omniroute_get_provider_metrics	read:health	Metrik setiap penyedia dengan kependaman p50/p95/p99 dan keadaan pemutus litar
omniroute_best_combo_for_task	read:combos, read:health	Syorkan gabungan mengikut jenis tugas dengan kekangan bajet/kependaman
omniroute_explain_route	read:health, read:usage	Terangkan sebab permintaan dihalakan kepada penyedia (faktor pemarkahan + sandaran)
omniroute_get_session_snapshot	read:usage	Petikan penuh sesi: kos, token, model/penyedia utama, ralat, kawalan bajet
omniroute_db_health_check	read:health, write:resilience	Diagnosis (dan pembaikan automatik pilihan) penyimpangan pangkalan data seperti rujukan gabungan rosak / baris yatim
omniroute_sync_pricing	pricing:write	Segerakkan data harga daripada sumber luaran (LiteLLM); menyokong dryRun

Alat Cache (2)

Alat	Skop	Penerangan
omniroute_cache_stats	read:cache	Statistik cache semantik, cache gesaan dan keidempotenan
omniroute_cache_flush	write:cache	Kosongkan cache secara global atau mengikut tandatangan/model

Alat Pemampatan (13)

Alat	Skop	Penerangan
omniroute_compression_status	read:compression	Tetapan pemampatan, ringkasan analitik dan statistik peka cache (termasuk metadata analytics.mcpDescriptionCompression)
omniroute_compression_configure	write:compression	Konfigurasikan mod pemampatan, ambang, nisbah sasaran, pengekalan gesaan sistem dan togol pemampatan penerangan MCP
omniroute_set_compression_engine	write:compression	Pilih enjin aktif (off/caveman/rtk/stacked) dan keamatan Caveman/RTK
omniroute_list_compression_combos	read:compression	Senaraikan gabungan pemampatan bernama dan saluran paip enjinnya
omniroute_compression_combo_stats	read:compression	Analitik yang dikumpulkan mengikut gabungan pemampatan dan enjin
omniroute_ccr_store	write:compression	Simpan kandungan yang diasingkan mengikut pemanggil dalam stor CCR dalam memori yang dibatasi dan kembalikan penanda serta rujukan ccr://
omniroute_ccr_retrieve	read:compression	Dapatkan kandungan CCR sepenuhnya atau dengan mod kepala, ekor, baris, grep dan statistik
omniroute_ccr_inspect	read:compression	Periksa metadata CCR milik pemanggil tanpa mengembalikan kandungan
omniroute_ccr_list	read:compression	Senaraikan metadata berhalaman untuk blok CCR milik pemanggil
omniroute_ccr_delete	write:compression	Padam blok CCR milik pemanggil
omniroute_ccr_stats	read:compression	Laporkan penggunaan memori dalam skop pemanggil, pembilang kitar hayat dan had stor
omniroute_rtk_discover	read:compression	Temukan hingar berulang dalam sampel output RTK yang disertakan secara pilihan
omniroute_rtk_learn	read:compression	Jana draf penapis RTK yang boleh disemak daripada sampel yang disertakan secara pilihan

Entri CCR hanya berada dalam memori dan akan hilang apabila dimulakan semula. Setiap blok dihadkan kepada 2 MiB, setiap prinsipal kepada 16 MiB dan stor global kepada 64 MiB. Entri secara lalai mempunyai TTL 24 jam (maksimum tujuh hari). Pengambilan MCP penuh dihadkan kepada 256 KiB; blok yang lebih besar kekal tersedia melalui mod julat dan grep. Penyimpanan, pengambilan, penyenaraian, pemeriksaan, pemadaman dan statistik diasingkan mengikut prinsipal kunci API yang disahkan. Rekod audit mengandungi cincangan dan metadata saiz, bukan kandungan.

omniroute_compression_status melaporkan pemampatan perihalan MCP secara berasingan di bawah analytics.mcpDescriptionCompression. Nilai tersebut ialah anggaran saiz metadata untuk perihalan MCP yang boleh disenaraikan (tools, prompts, resources, dan resourceTemplates); nilai tersebut bukan resit penggunaan penyedia dan ditandai dengan source: "mcp_metadata_estimate".

Penapis Pepohon Kebolehcapaian MCP (v3.8.0)

Berasingan daripada alat pemampatan di atas, OmniRoute menyertakan penapis pascapelaksanaan yang memampatkan hasil alat bagi alat pelayar/kebolehcapaian MCP sebelum hasil tersebut dikembalikan kepada ejen. Penapis ini bukan alat — ia berjalan secara telus pada sebarang hasil alat yang mengandungi teks pepohon kebolehcapaian atau petikan pelayar yang berjela-jela (≥2000 aksara).

Tingkah laku utama:

• Meruntuhkan ≥30 baris saudara berulang yang berturutan kepada ringkasan bahagian awal + akhir
• Mengekalkan penambat [ref=eXX] yang diperlukan oleh Playwright/penggunaan komputer
• Memotong paksa teks bersaiz terlalu besar (>50,000 aksara) dengan petunjuk navigasi
• Penjimatan dijangka: 60–80% pada muatan petikan pelayar

Konfigurasi: compression.mcpAccessibility dalam tetapan global (migrasi 056). Pelaksanaan: open-sse/services/compression/engines/mcpAccessibility/. Dokumentasi penuh: Enjin Pemampatan — Penapis Pepohon Kebolehcapaian MCP.

Lihat Enjin Pemampatan dan Pemampatan RTK untuk model pemampatan masa jalan yang menyokong alat ini.

Alat 1Proxy (3)

Alat	Skop	Penerangan
omniroute_oneproxy_fetch	read:proxies	Dapatkan proksi percuma daripada pasaran 1proxy (penapis protokol/negara/kualiti/had)
omniroute_oneproxy_rotate	read:proxies	Dapatkan proksi tersedia yang seterusnya mengikut strategi (random / quality / sequential)
omniroute_oneproxy_stats	read:proxies	Statistik kumpulan, status penyegerakan, taburan mengikut protokol dan negara

Alat Memori (3)

Ditakrifkan dalam open-sse/mcp-server/tools/memoryTools.ts. Pengesahan/skop dikuatkuasakan melalui saluran skop MCP standard.

Alat	Skop	Penerangan
omniroute_memory_search	read:memory	Cari memori mengikut pertanyaan / jenis / kunci API dengan penguatkuasaan belanjawan token
omniroute_memory_add	write:memory	Tambah entri memori baharu (factual / episodic / procedural / semantic)
omniroute_memory_clear	write:memory	Kosongkan memori untuk kunci API, dengan pilihan penapisan mengikut jenis atau cap masa olderThan

Alat Kemahiran (4)

Ditakrifkan dalam open-sse/mcp-server/tools/skillTools.ts. Disokong oleh src/lib/skills/registry + src/lib/skills/executor.

Alat	Skop	Penerangan
omniroute_skills_list	read:skills	Senaraikan kemahiran berdaftar dengan pilihan penapisan mengikut kunci API, nama atau status didayakan
omniroute_skills_enable	write:skills	Dayakan atau nyahdayakan kemahiran tertentu mengikut ID
omniroute_skills_execute	execute:skills	Laksanakan kemahiran dengan input yang diberikan dan kembalikan rekod pelaksanaan
omniroute_skills_executions	read:skills	Senaraikan sejarah pelaksanaan kemahiran terkini

Sumber Konteks Notion (6)

Ditakrifkan dalam open-sse/mcp-server/tools/notionTools.ts. Token disimpan dalam jadual key_value melalui src/lib/db/notion.ts. Klien REST dalam src/lib/notion/api.ts. API tetapan dalam src/app/api/settings/notion/route.ts. UI papan pemuka dalam src/app/(dashboard)/dashboard/endpoint/components/NotionSourceCard.tsx.

Konfigurasikan token integrasi Notion anda daripada tab Sumber Konteks dalam papan pemuka Endpoint, atau melalui API REST:

# Tetapkan token
curl -X POST http://localhost:20128/api/settings/notion \
  -H "Content-Type: application/json" \
  -d '{"token": "ntn_..."}'

# Semak status
curl http://localhost:20128/api/settings/notion

# Putuskan sambungan
curl -X DELETE http://localhost:20128/api/settings/notion

Alat	Skop	Penerangan
notion_search	read:notion	Carian teks penuh merentasi semua halaman dan pangkalan data
notion_get_page	read:notion	Dapatkan halaman mengikut ID berserta sifatnya
notion_list_block_children	read:notion	Senaraikan blok anak bagi halaman atau blok
notion_query_database	read:notion	Buat pertanyaan pangkalan data dengan penapis, susunan dan penomboran halaman
notion_get_database	read:notion	Dapatkan skema pangkalan data mengikut ID
notion_append_blocks	write:notion	Tambahkan blok anak pada blok induk (maksimum 100 bagi setiap permintaan)

Alat Katalog Kemahiran Ejen (3)

Ditakrifkan dalam open-sse/mcp-server/tools/agentSkillTools.ts. Disokong oleh src/lib/agentSkills/catalog. Alat ini mendedahkan katalog dokumentasi Kemahiran Ejen yang mengandungi 45 entri kepada klien MCP dan ejen luaran. Skop: read:catalog.

Alat	Skop	Penerangan
omniroute_agent_skills_list	read:catalog	Senaraikan kesemua 45 kemahiran ejen dengan penapis pilihan category (api|cli) dan area; mengembalikan metadata + liputan
omniroute_agent_skills_get	read:catalog	Dapatkan metadata penuh + kandungan SKILL.md untuk satu kemahiran berdasarkan id kanonik
omniroute_agent_skills_coverage	read:catalog	Statistik liputan: bilangan daripada 23 kemahiran API, 21 CLI dan 1 konfigurasi yang mempunyai fail SKILL.md dalam sistem fail berbanding jumlah katalog

Lihat AGENT-SKILLS.md untuk katalog penuh dan cara ejen luaran menggunakannya.

Rangka Kerja Berkaitan (v3.8.0)

Inventori alat MCP di atas (110 alat unik, dikira oleh countUniqueMcpTools()) sengaja dihadkan kepada operasi penghalaan/cache/pemampatan/memori/kemahiran/proksi/sumber-konteks masa jalan. Dua rangka kerja bersebelahan disertakan bersama pelayan MCP dalam v3.8.0 dan didokumentasikan secara berasingan:

Ejen Awan

Ejen Awan ialah ejen pengekodan AI luar proses (codex-cloud, cursor-cloud, devin, jules) yang disepadukan ke dalam OmniRoute melalui model sambungan yang sama seperti yang digunakan untuk penyedia LLM. Ejen ini didedahkan melalui permukaan REST tersendiri (/api/v1/agents/*) dan bukan sebahagian daripada katalog alat MCP — memanggil Ejen Awan tidak menggunakan skop MCP.

• Pelaksanaan: src/lib/cloudAgent/ (registry.ts, agents/codex.ts, agents/cursor.ts, agents/devin.ts, agents/jules.ts).
• Kitar hayat: createTask, getStatus, approvePlan, sendMessage, listSources.
• Dokumentasi: docs/frameworks/CLOUD_AGENT.md.

Kawalan Keselamatan

Kawalan keselamatan ialah penapis pra/pasca pelaksanaan (vision-bridge, pii-masker, prompt-injection) yang digunakan dalam saluran sembang. Penapis ini dijalankan sebelum lapisan alat/laluan MCP dicapai dan mengeluarkan pelanggaran berstruktur kepada saluran audit; penapis ini tidak dipanggil sebagai alat MCP.

• Pelaksanaan: src/lib/guardrails/.
• Dokumentasi: docs/security/GUARDRAILS.md.

Apabila menyahpepijat panggilan MCP yang kelihatan disekat, semak kedua-dua log audit MCP (entri scope_denied:*) dan jejak audit kawalan keselamatan — permintaan mungkin ditolak oleh kawalan keselamatan sebelum ia mencapai lapisan penguatkuasaan skop MCP.

---

Titik Akhir REST API

Titik Akhir	Kaedah	Penerangan	Pengesahan
/api/mcp/status	GET	Status pelayan: denyutan jantung, keadaan pengangkutan HTTP, ringkasan aktiviti audit	Pengurusan (sesi/pentadbir)
/api/mcp/tools	GET	Katalog alat (nama, penerangan, skop, fasa, titik akhir sumber)	Pengurusan
/api/mcp/sse	GET / POST	Titik akhir pengangkutan SSE (dikawal oleh mcpEnabled + mcpTransport === "sse")	Kunci API + skop
/api/mcp/stream	POST/GET/DELETE	Pengangkutan HTTP boleh distrim (menggunakan pengepala mcp-session-id; DELETE menamatkan sesi)	Kunci API + skop
/api/mcp/audit	GET	Entri log audit daripada mcp_tool_audit (penapis: limit, offset, tool, success, apiKeyId)	Pengurusan
/api/mcp/audit/stats	GET	Statistik audit teragregat (totalCalls, successRate, avgDurationMs, alat teratas)	Pengurusan

Fail sumber: src/app/api/mcp/{status,tools,sse,stream,audit,audit/stats}/route.ts.

Kedua-dua pengangkutan SSE dan HTTP Boleh Distrim disekat sehingga pelayan MCP didayakan dalam Tetapan (mcpEnabled) dan mcpTransport yang sesuai dipilih. Jika pengangkutan yang salah dikonfigurasikan, laluan tersebut mengembalikan HTTP 400 dengan petunjuk untuk menukar tetapan.

---

Pengesahan & Skop

Alat MCP disahkan melalui skop kunci API. Penguatkuasaan skop dipusatkan dalam open-sse/mcp-server/scopeEnforcement.ts. Setiap alat memerlukan skop tertentu:

Skop	Alat
read:health	get_health, get_provider_metrics, simulate_route, explain_route, best_combo_for_task, db_health_check
read:combos	list_combos, get_combo_metrics, simulate_route, best_combo_for_task, test_combo
write:combos	switch_combo, set_routing_strategy
read:quota	check_quota
read:usage	cost_report, get_session_snapshot, explain_route
read:models	list_models_catalog
execute:completions	route_request, test_combo
execute:search	web_search, x_search, web_fetch
write:budget	set_budget_guard
write:resilience	set_resilience_profile, db_health_check
pricing:write	sync_pricing
read:cache	cache_stats
write:cache	cache_flush
read:compression	compression_status, list_compression_combos, compression_combo_stats
write:compression	compression_configure, set_compression_engine
read:proxies	oneproxy_fetch, oneproxy_rotate, oneproxy_stats
read:notion	notion_search, notion_get_page, notion_list_block_children, notion_query_database, notion_get_database
write:notion	notion_append_blocks
read:memory	memory_search
write:memory	memory_add, memory_clear
read:skills	skills_list, skills_executions
write:skills	skills_enable
execute:skills	skills_execute
read:catalog	agent_skills_list, agent_skills_get, agent_skills_coverage
read:tools	omniroute_tool_search
read:radar	omniroute_radar_catalog
read:gamification	gamification_profile, gamification_rank, gamification_leaderboard, gamification_badges, gamification_servers, gamification_anomalies
write:gamification	gamification_invite, gamification_transfer
read:plugins	plugin_list, plugin_executions
write:plugins	plugin_scan, plugin_install, plugin_uninstall, plugin_activate, plugin_deactivate, plugin_configure
read:obsidian	13 alat baca — obsidian_list_vault, obsidian_read_note, obsidian_search_simple, obsidian_search_structured, obsidian_get_periodic_note, obsidian_sync_status, …
write:obsidian	9 alat tulis — obsidian_write_note, obsidian_append_note, obsidian_patch_note, obsidian_move_note, obsidian_delete_note, obsidian_sync_trigger, …
read:local-corpus	local_corpus_search, local_corpus_read, local_corpus_status

Skop kad bebas disokong: read:* memberikan semua skop baca, * memberikan akses penuh.

mcp:connect — keupayaan laluan terhad (#7895)

Untuk mencapai pengangkutan HTTP/SSE MCP (/api/mcp/*) dari alamat bukan gelung balik, pengecualian LOCAL_ONLY /api/mcp/ diperlukan (lihat docs/security/ROUTE_GUARD_TIERS.md). Sebelum ini, pengecualian tersebut hanya menerima kunci API dengan skop penuh manage/admin — terlalu luas bagi pemanggil yang hanya perlu berkomunikasi dengan MCP. src/shared/constants/managementScopes.ts kini mengeksport MCP_CONNECT_SCOPE = "mcp:connect": skop tambahan yang terhad (mengikut pendekatan terdahulu yang sama seperti SELF_USAGE_SCOPE) yang membenarkan HANYA pemintasan /api/mcp/ dalam src/server/authz/policies/management.ts — ia tidak memberikan akses kepada mana-mana laluan pengurusan lain dan sengaja TIDAK disertakan dalam MANAGEMENT_API_KEY_SCOPES. Kunci yang mempunyai manage/admin masih melepasi pengecualian tersebut tanpa perubahan; mcp:connect ialah alternatif dengan keistimewaan lebih rendah untuk pemanggil jauh yang hanya menggunakan MCP, yang disemak melalui hasMcpConnectOrManageScope().

Pengikatan skop HTTP bagi setiap kunci (#7895)

Melalui HTTP/SSE, open-sse/mcp-server/httpTransport.ts kini mendapatkan api_keys.scopes sebenar pemanggil melalui resolveMcpCallerAuthInfo() (open-sse/mcp-server/httpAuthContext.ts) dan menghantarnya kepada transport.handleRequest(req, { authInfo }) milik SDK MCP, supaya extra.authInfo.scopes yang sampai kepada setiap panggilan alat mencerminkan skop kunci Bearer itu sendiri. resolveCallerScopeContext() dalam scopeEnforcement.ts sememangnya telah mengutamakan authInfo berbanding _meta dan sandaran env OMNIROUTE_MCP_SCOPES — perubahan ini hanya mengisi sumber pertama dengan keutamaan tertinggi tersebut, yang sebelum ini tidak dibekalkan melalui HTTP. Apabila tiada kunci API berjaya dikenal pasti (tiada pengepala, kunci tidak sah), authInfo kekal undefined dan penyelesaian diteruskan kepada rantaian meta/env sedia ada tanpa perubahan. Ini TIDAK mengubah lalai OMNIROUTE_MCP_ENFORCE_SCOPES — penguatkuasaan masih perlu didayakan secara eksplisit; perubahan ini hanya memastikan laluan setiap kunci diutamakan selepas penguatkuasaan didayakan. stdio tidak mempunyai identiti bagi setiap pemanggil (lihat mcpCallerIdentity.ts) dan tidak terjejas — ia kekal menggunakan rantaian sandaran _meta/env.

---

Pemboleh Ubah Persekitaran

Pemboleh Ubah	Lalai	Tujuan
OMNIROUTE_BASE_URL	http://localhost:20128	URL asas yang digunakan oleh pelayan MCP semasa memanggil API dalaman OmniRoute
OMNIROUTE_API_KEY	(kosong)	Kunci API yang dimajukan sebagai Authorization: Bearer kepada panggilan API dalaman
OMNIROUTE_MCP_ENFORCE_SCOPES	false (hanya "true" mengaktifkannya)	Apabila diaktifkan, skop yang tiada akan menolak panggilan alat dan merekodkan scope_denied:<reason> dalam log audit
OMNIROUTE_MCP_SCOPES	(kosong)	Senarai skop dipisahkan koma yang dianggap "tersedia" secara lalai (digunakan apabila pemanggil tidak menyediakan skopnya sendiri)
OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS	(tidak ditetapkan = aktif)	Apabila ditetapkan kepada 0/false/off/no, menyahaktifkan pemampatan perihalan MCP semasa pendaftaran
OMNIROUTE_MCP_DESCRIPTION_COMPRESSION	(tidak ditetapkan = aktif)	Alias alternatif untuk togol yang sama seperti di atas
OMNIROUTE_MCP_FETCH_TIMEOUT_MS	10000	Had masa sebelum pembatalan untuk bacaan pengurusan dalaman (kesihatan, daya tahan, gabungan, kuota, penggunaan)
OMNIROUTE_MCP_UPSTREAM_TIMEOUT_MS	60000	Had masa sebelum pembatalan untuk lompatan yang menunggu penyedia (route_request, web_search, web_fetch)
MCP_TOOL_DENY	(tidak ditetapkan = tiada penapis)	Nama alat dipisahkan koma untuk digugurkan daripada tools/list (pengurangan kardinaliti alat — lihat di bawah)
MCP_TOOL_ALLOW	(tidak ditetapkan = tiada penapis)	Nama alat dipisahkan koma untuk dikekalkan secara eksklusif (mod senarai dibenarkan — lihat di bawah)
DATA_DIR	~/.omniroute	Fail denyutan jantung ditulis ke ${DATA_DIR}/runtime/mcp-heartbeat.json

---

Pemampatan Perihalan

Daftar alat, gesaan, dan sumber MCP boleh memampatkan perihalan semasa pendaftaran/penyenaraian untuk mengurangkan jejak metadata yang didedahkan kepada klien (dan seterusnya kos konteks gesaan). Pelaksanaannya terletak dalam open-sse/mcp-server/descriptionCompressor.ts dan disepadukan ke dalam pelayan MCP melalui compressMcpRegistryMetadata di dalam createMcpServer().

• Pemampatan dijalankan ke atas teks perihalan menggunakan set peraturan Caveman (getRulesForContext("all", "full")) dengan pengekstrakan blok terpelihara (rentang kod, blok berpagar dan sebagainya) supaya kandungan berstruktur tidak diubah.
• Togol bagi setiap penggunaan melalui nilai compression.mcpDescriptionCompressionEnabled dalam jadual tetapan key_value (lalai: diaktifkan) — dipaparkan dalam UI sebagai Analitik → Pemampatan perihalan MCP.
• Togol untuk seluruh proses melalui sama ada OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS=false atau OMNIROUTE_MCP_DESCRIPTION_COMPRESSION=false.
• Statistik masa nyata dipaparkan melalui omniroute_compression_status di bawah analytics.mcpDescriptionCompression dan ditandai dengan source: "mcp_metadata_estimate" untuk membezakannya daripada rekod penggunaan penyedia sebenar.

---

Pengurangan Kardinaliti Alat (F4.3)

Pemampatan perihalan mengecilkan metadata setiap alat; pengurangan kardinaliti alat melangkah lebih jauh dengan mengurangkan bilangan alat yang diumumkan. Mengiklankan lebih sedikit alat dalam manifes tools/list mengurangkan kos token bagi setiap permintaan yang perlu ditanggung oleh model klien untuk katalog alat (pemampatan "lapisan 5"). Pelaksanaannya ialah penapis tulen tanpa keadaan dalam open-sse/mcp-server/toolCardinality.ts (reduceToolManifest), yang disepadukan ke dalam gelung pendaftaran dalam createMcpServer() (open-sse/mcp-server/server.ts).

Perlu didayakan secara pilihan, dilumpuhkan secara lalai. Penapis hanya berjalan apabila sekurang-kurangnya satu daripada dua pemboleh ubah persekitaran ditetapkan; apabila kedua-duanya tidak ditetapkan, kesemua 110 alat diumumkan tanpa perubahan.

Pemboleh ubah	Mod
MCP_TOOL_DENY	Senarai hitam — nama alat yang dipisahkan koma dan sentiasa digugurkan daripada tools/list
MCP_TOOL_ALLOW	Senarai dibenarkan — nama alat yang dipisahkan koma; hanya alat ini dikekalkan, yang lain digugurkan

deny diberi keutamaan berbanding allow. Nama dipisahkan dengan koma, ruang kosong di awal dan akhir dibuang, dan entri kosong diabaikan. Contoh:

# Gugurkan dua alat daripada katalog
MCP_TOOL_DENY="omniroute_get_health,omniroute_list_combos" omniroute --mcp

# Umumkan hanya alat penghalaan + kuota (mod senarai dibenarkan)
MCP_TOOL_ALLOW="omniroute_route_request,omniroute_check_quota" omniroute --mcp

Cara alat yang ditapis dialih keluar: pendaftaran sentiasa berjaya; alat yang ditolak oleh profil kemudiannya dikenakan .disable() pada pemegang MCP SDK, jadi alat itu tidak pernah muncul dalam tools/list tetapi pendawaiannya kekal utuh (pengaktifan/penyahaktifan yang bersih, tanpa pendaftaran semula). Penghurai profil ialah readMcpToolProfileFromEnv(process.env), yang mengembalikan null (tiada penapisan) apabila kedua-dua pemboleh ubah kosong.

Bentuk ToolProfile yang lebih kaya di sebalik reduceToolManifest turut menyokong penapisan persilangan skop (allowScopes, dengan pemadanan kad bebas gaya read:*) dan had maxTools yang deterministik, tetapi kedua-dua tetapan tersebut memerlukan manifes penuh pada waktu pendaftaran dan tidak didedahkan melalui pemboleh ubah persekitaran pada masa ini (cangkuk peringkat tools/list ialah susulan yang sedang dijejaki). estimateManifestTokens() tersedia untuk membandingkan kos token manifes sebelum dan selepas pengurangan.

---

Denyutan Jantung Masa Jalan

Pengangkutan stdio menyimpan status keaktifan ke ${DATA_DIR}/runtime/mcp-heartbeat.json setiap 5 saat. Papan pemuka (/api/mcp/status) membaca fail ini bersama-sama status keaktifan PID untuk menentukan online. Sebaliknya, pengangkutan HTTP melaporkan keadaan daripada getMcpHttpStatus() dalam proses (tanpa penulisan fail).

Petikan keadaan denyutan jantung mengandungi:

{
  "pid": 12345,
  "startedAt": "2026-05-13T12:34:56.000Z",
  "lastHeartbeatAt": "2026-05-13T12:35:01.000Z",
  "version": "1.8.1",
  "transport": "stdio",
  "scopesEnforced": false,
  "allowedScopes": [],
  "toolCount": 110
}

---

Pengelogan Audit

Setiap panggilan alat direkodkan ke jadual SQLite mcp_tool_audit oleh open-sse/mcp-server/audit.ts:

• Nama alat, argumen (dicincang/dipendekkan mengikut auditLevel bagi setiap alat), hasil
• Tempoh dalam ms, penanda kejayaan/kegagalan, mesej ralat (jika berkenaan)
• Cincangan kunci API, cap masa
• Penolakan skop direkodkan sebagai scope_denied:<reason> bersama senarai skop yang tiada

Gunakan papan pemuka atau titik akhir REST /api/mcp/audit dan /api/mcp/audit/stats untuk memeriksa panggilan terkini.

---

Fail

Fail	Tujuan
open-sse/mcp-server/server.ts	Kilang pelayan MCP, titik masuk stdio, pendaftaran alat berskop
open-sse/mcp-server/httpTransport.ts	Pengangkutan SSE + HTTP Boleh Distrim (pengurusan sesi)
open-sse/mcp-server/scopeEnforcement.ts	Penilaian skop alat dan penyelesaian pemanggil
open-sse/mcp-server/audit.ts	Pengelogan audit panggilan alat (mcp_tool_audit)
open-sse/mcp-server/runtimeHeartbeat.ts	Penulis denyutan stdio (mcp-heartbeat.json)
open-sse/mcp-server/descriptionCompressor.ts	Pemampatan perihalan untuk daftar alat / gesaan / sumber
open-sse/mcp-server/schemas/tools.ts	Skema Zod + daftar alat (MCP_TOOLS, 45 entri)
open-sse/mcp-server/tools/advancedTools.ts	Pengendali alat Fasa 2 + cache + 1proxy
open-sse/mcp-server/tools/compressionTools.ts	Pengendali alat pemampatan
open-sse/mcp-server/tools/memoryTools.ts	Takrif alat memori (3 alat)
open-sse/mcp-server/tools/skillTools.ts	Takrif alat kemahiran (4 alat)
open-sse/mcp-server/tools/notionTools.ts	Takrif alat sumber konteks Notion (6 alat)
open-sse/mcp-server/tools/gamificationTools.ts	Takrif alat gamifikasi (8 alat)
open-sse/mcp-server/tools/pluginTools.ts	Alat pendaftaran dan pengurusan pemalam (8 alat)
src/app/api/mcp/status/route.ts	Titik akhir /api/mcp/status
src/app/api/mcp/tools/route.ts	Titik akhir /api/mcp/tools
src/app/api/mcp/sse/route.ts	Laluan pengangkutan SSE /api/mcp/sse
src/app/api/mcp/stream/route.ts	Laluan pengangkutan HTTP Boleh Distrim /api/mcp/stream
src/app/api/mcp/audit/route.ts	Pertanyaan log audit /api/mcp/audit
src/app/api/mcp/audit/stats/route.ts	Metrik audit teragregat /api/mcp/audit/stats
src/lib/notion/api.ts	Klien REST API Notion (percubaan semula, tamat masa, pengelasan ralat)
src/lib/db/notion.ts	Pengekalan token Notion (jadual key_value)
src/app/api/settings/notion/route.ts	API tetapan Notion (GET/POST/DELETE)
src/app/(dashboard)/dashboard/endpoint/components/NotionSourceCard.tsx	UI pengurusan token Notion
tests/unit/notion-api.test.ts	Ujian klien API Notion (7)
tests/unit/notion-tools.test.ts	Ujian penguatkuasaan skop alat Notion (10)
tests/unit/db/notion.test.mjs	Ujian modul DB Notion (3)