mcp-server-starter
yazelin/mcp-server-starter
Dependency-light MCP server starter for learning JSON-RPC tools, workspace boundaries, and agent integrations.
Instalação
npx convez-ai yazelin/mcp-server-starter1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
MCP Server Starter
Learn MCP by building a tiny dependency-light tool server.
繁中定位
MCP Server 入門模板 面向台灣繁中受眾。
- 主要受眾:適合想讓 Claude、Cursor、Agent 調用自家工具/API 的開發者。
- 核心承諾:用最小 JSON-RPC MCP server 看懂工具註冊、工具呼叫與安全邊界。
- CTA 頁:https://yazelin.github.io/mcp-server-starter/
公開教學文件
這個 repo 的教學內容直接公開,讓你可以先自己照著跑;如果需要手把手 debug、改成你的公司或個人場景,再考慮工作坊或顧問協助。
- 網頁版教學:https://yazelin.github.io/mcp-server-starter/tutorial.html
- Markdown 教學:
docs/ - 快速開始:
docs/01-quickstart.md - 常見踩雷:
docs/05-common-pitfalls.md - 後半段(FastMCP 對照組):
docs/08-fastmcp-comparison.md
Who this is for
Developers who want to connect Claude/Cursor/agents to their own tools.
Features
- JSON-RPC stdio server
- Example tools: echo, now, read_text_file, word_count
- Workspace safety boundary
- Smoke test client
- FastMCP rewrite of the same tools (optional
fastmcpextra) — seedocs/08-fastmcp-comparison.md
Quick start
本教學以 uv 為主。uv sync 會依 pyproject.toml + uv.lock 自動建立 .venv 並把專案裝好(毋須手動 venv / activate),uv run 直接在那個環境裡執行。以下 uv sync / uv run 在 Ubuntu 與 Windows 完全相同。
先安裝 uv(一次就好):
- Ubuntu / macOS:
curl -LsSf https://astral.sh/uv/install.sh | sh - Windows(PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
裝完重開終端機,uv --version 印得出版本就 OK。
git clone https://github.com/yazelin/mcp-server-starter.git
cd mcp-server-starter
uv sync
# Run the smoke test (spawns server.py over stdio, exercises the protocol +
# the workspace security boundary, and asserts the results — non-zero on failure)
uv run python client_smoke_test.py
# Or start the stdio server directly and pipe JSON-RPC into it
MCP_WORKSPACE="$PWD" uv run python server.py
# Or run the installed console script (same stdio JSON-RPC server)
MCP_WORKSPACE="$PWD" uv run mcp-server-starter
後半段:FastMCP 版(對照組)
uv sync --extra fastmcp
MCP_SMOKE_TARGET=server_fastmcp.py uv run python client_smoke_test.py # 同一份測試也過
MCP_WORKSPACE="$PWD" uv run mcp-server-starter-fastmcp # 啟動 FastMCP server
Configuration is a single environment variable, MCP_WORKSPACE, which bounds
what read_text_file is allowed to read. If unset, it defaults to the current
working directory. There is no .env file and no required third-party dependency — the front half is pure stdlib; FastMCP is an optional extra (--extra fastmcp).
這個 starter 只用 Python 標準函式庫,[project].dependencies 是空的,所以 uv sync 只會 build 並安裝本專案這一個 package。沒裝 uv 的話 pip install . 也能裝,但本教學以 uv 為主。
Learn / get help
This repo is also a CTA page for workshops and consulting:
- GitHub Pages: https://yazelin.github.io/mcp-server-starter/
- Contact: yazelin@ching-tech.com
License
MIT
Brand / CTA design
- Landing page: https://yazelin.github.io/mcp-server-starter/
- CI spec: DESIGN.md
- Banner: assets/banner.svg
- Logo: assets/logo.svg
關於作者
這個範本由 林亞澤(Yaze Lin) 維護 — 出身機電自動化系統整合,現在把同一套工程方法用在 AI 產品上。
- 任職於 擎添工業 ChingTech(1984 年成立的機電自動化公司:PLC 程式、機械手臂、AGV 無人搬運、半導體封測/PCB/面板/光學產線整合)。
- 技術筆記與更多範例:yazelin.github.io · GitHub @yazelin
從範本到正式產品
把工具安全交給 AI 這條線,我們做成了 AgentOS(agent 治理)與 Mori Desktop(個人 AI 管家)。
如果你想看同樣的想法做成正式、上線中的產品:
- CTOS — 企業 AI 工作平台:macOS 風格 Web 桌面、知識庫 RAG 檢索、產業專屬 Agent、LINE Bot 整合,資料留在台灣。ching-tech.com · 品牌站
- CTOS-Lite / CT JINN — 把公司裝進 LINE 的個人版 AI 助理,加 LINE 即可試用:@285fjkky
- Mori Desktop — 個人 AI 管家桌面應用(Tauri 2 + Rust + React):github.com/yazelin/mori-desktop
- AgentOS — 跨 CLI 的 agent 治理平台(開發中)
想把這個範本落地成你公司的內部系統,或想上一堂從 0 到部署的課? 來信 yazelin@ching-tech.com,或追蹤上面的連結。