mcp-toolkit
Provides read-only SQLite querying capabilities, allowing SELECT/WITH/PRAGMA statements against SQLite databases.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-toolkit Use the health check tool to show service version and uptime"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-toolkit
把分散的手写工具能力,标准化为 8 个即插即用的 MCP 工具。任何支持 Model Context Protocol 的宿主(Claude Desktop / Cherry Studio / Cline / MCP Inspector)都能通过 stdio 直接调用。
为什么做这个项目
写过一个又一个后端小项目后,发现很多「手写工具」能力高度可复用,却散落在不同仓库里:聚合排名的热度公式、腾讯云 TC3 签名器、RAG 切块逻辑、JWT 双令牌经验…… MCP(Model Context Protocol)正是把这些能力「一次封装、处处复用」的标准协议——写成一个 MCP 服务器,任何 AI 宿主都能即插即用。
本项目是一次「从 0 手写 MCP 服务器」的完整实践:不抄模板,逐行理解协议、分层设计、单测对拍官方向量。
Related MCP server: tool-mcp-server
架构
┌────────────────────────────────────────────────────────────┐
│ MCP 宿主(任意) │
│ Claude Desktop / Cherry Studio / Cline / Inspector │
└──────────────────────────┬─────────────────────────────────┘
│ JSON-RPC over stdio
┌──────────────────────────▼─────────────────────────────────┐
│ src/index.ts │
│ McpServer + StdioServerTransport(协议入口) │
│ 注册 8 个工具,日志走 stderr 不污染协议流 │
└──────────────────────────┬─────────────────────────────────┘
│
┌──────────────────────────▼─────────────────────────────────┐
│ src/tools/(薄壳层) │
│ 每个工具 = zod schema + handler 转发,不含业务逻辑 │
│ travel_hotspot_rank · tc3_sign · text_chunk · date_calc │
│ sqlite_query · webpage_extract · jwt_decode · health_ping │
└──────────────────────────┬─────────────────────────────────┘
│ 只调用纯函数
┌──────────────────────────▼─────────────────────────────────┐
│ src/lib/(纯函数层) │
│ 零 MCP 依赖、零副作用,可独立单测 │
│ hotspot · tc3 · chunk · date · sqlite · webpage · jwt · health │
└────────────────────────────────────────────────────────────┘分层铁律:业务逻辑全部在 lib/ 纯函数(可脱离 MCP 独立测试);tools/ 只做「zod 校验 + 转发」,保持极薄、一眼看懂。
8 个工具
工具 | 说明 | 能力来源 |
| 地点口碑榜聚合: | 复用 travel-rank 聚合算法 |
| 腾讯云 API 3.0 TC3-HMAC-SHA256 签名请求头(含 Authorization) | 复用 python-learning-agent 签名器 |
| RAG 文本切块:滑动窗口 + overlap,优先句末断点 | 复用 RAG 预处理经验 |
| 日期计算:加减/求差/星期/闰年/当月天数/今天(UTC 规避跨日误差) | 独立纯函数 |
| SQLite 只读查询(SELECT/WITH/PRAGMA),readOnly 打开杜绝写操作;可读路径受 | Node 22 内置 |
| 抓取网页抽取纯文本:标题/标题层级/链接/正文(带超时) | 独立纯函数 |
| JWT 解码 + HMAC 验签(HS256/384/512,常量时间比较) | 复用 campus-mutual-aid JWT 经验 |
| 健康检查:服务名/版本/运行时长/Node 版本/平台 | 独立纯函数 |
快速开始
# 依赖(需 Node >= 22.5,因为用到了内置 node:sqlite)
npm install
# 类型检查 + 构建
npm run typecheck && npm run build
# 单元测试(50 个用例)
npm test
# 端到端冒烟测试(连上编译产物走完整协议链路)
node examples/smoke-client.mjs在 MCP Inspector 里手动调试
npx @modelcontextprotocol/inspector node dist/index.js浏览器打开后即可可视化地列出工具、传参调用。
接入 Claude Desktop
把 examples/claude_desktop_config.json 合并到 claude_desktop_config.json(路径改成你自己的绝对路径),重启 Claude Desktop 即可。
设计决策(面试叙事)
分层:
lib/纯函数 +tools/薄壳,业务逻辑可脱离 MCP 独立测试,也让每个文件职责单一、review 一眼看懂。零第三方依赖的签名器:TC3-HMAC-SHA256 用 Node 内置
node:crypto实现,密钥只走函数入参/环境变量、绝不入日志;用腾讯云官方公开测试向量做单测对拍(HashedCanonicalRequest逐字节一致)。只读 SQLite 三重保险:
sqlite_query①用正则限制语句前缀(只允许 SELECT/WITH/PRAGMA)、②以readOnly: true打开、③限制可读路径的根目录。前两条杜绝写操作,第三条杜绝「本机任意 sqlite 都能读」。路径边界由环境变量
MCP_SQLITE_ROOT指定,不设则用进程工作目录;dbPath必须落在该目录内。判边界分两层:先按解析后的字面路径判(挡住
..与越界绝对路径),再按realpath判(挡住软链接绕过)。为什么需要第三条:MCP 宿主里的模型可能被间接提示注入(读到不可信内容后被诱导继续调工具)——一个不设边界的读取工具就是数据外泄面。「不可信返回内容不得扩大工具权限」这条原则,落到工具层就是这个边界。
node:sqlite的坑:它是 Node 22 实验内置模块,不在builtinModules清单里,vite/vitest 会误当普通包解析失败 → 用createRequire运行时加载 + 纯类型查询绕开。日志隔离:stdio 下 stdout 走协议通信,日志一律写 stderr,避免污染 JSON-RPC 流。
安全:真实密钥通过
.env(已 gitignore)+ 环境变量注入,官方向量密钥只经TC3_SAMPLE_SECRET_KEY测试专用变量,不触发 GitHub Secret Scanning。
目录结构
mcp-toolkit/
├── src/
│ ├── index.ts # MCP 入口:注册 8 工具 + stdio 连接
│ ├── lib/ # 纯函数层(零 MCP 依赖)
│ │ ├── hotspot.ts # 地点热度聚合
│ │ ├── tc3.ts # TC3-HMAC-SHA256 签名
│ │ ├── chunk.ts # 文本滑动窗口切块
│ │ ├── date.ts # 日期计算
│ │ ├── sqlite.ts # SQLite 只读查询
│ │ ├── webpage.ts # 网页抓取 + 正文抽取
│ │ ├── jwt.ts # JWT 解码/验签
│ │ └── health.ts # 健康检查
│ └── tools/ # 薄壳层(zod schema + 转发)
│ └── *.ts # 8 个工具 + index.ts 统一注册
├── test/ # 50 个单测用例
├── examples/ # Claude Desktop 配置 + 冒烟客户端
├── .github/workflows/ci.yml
└── package.jsonLicense
Available Tools
8 toolsdate_calcA
日期计算:加减天数、求日期差、查星期几、判断闰年、查当月天数、取今天日期。日期统一 YYYY-MM-DD 格式,按 UTC 处理规避跨日误差。
Inputs: op (required), to, date, days, +3 more.
health_pingA
健康检查:返回服务名、版本、运行时长、Node 版本与平台信息,用于验证 MCP 服务器连通性。
Inputs: no named parameters.
jwt_decodeA
解码 JWT(不验签),解析 header 与 payload 并判断是否过期;提供 secret 时用 HMAC(HS256/384/512)验签。
Inputs: token (required), secret.
sqlite_queryA
对 SQLite 数据库执行只读查询(SELECT / WITH / PRAGMA)。基于 Node 内置 node:sqlite,以只读模式打开,拒绝任何写操作。
Inputs: sql (required), dbPath (required), params.
tc3_signA
生成腾讯云 API 3.0 的 TC3-HMAC-SHA256 签名请求头(含 Authorization)。密钥可入参或从环境变量 TC3_SECRET_ID / TC3_SECRET_KEY 读取,真实密钥不入日志。签名实现与官方公开测试向量逐字节一致。
Inputs: payload (required), host, action, region, +5 more.
text_chunkA
RAG 文本切块:把长文本按 chunkSize 切成若干片段,支持 overlap 重叠,优先在句末断点切割。适合做检索增强的预处理。
Inputs: text (required), overlap, chunkSize.
travel_hotspot_rankB
地点口碑榜聚合:输入地点列表与用户帖子,按「发帖数2 + 投票3 + 平均评分*5」计算热度并排序,同时聚合每地点的高频优点。算法源自 travel-rank 项目,面试可两边对拍。
Inputs: posts (required), locations (required).
webpage_extractA
抓取网页并抽取纯文本:返回标题、各级标题、链接列表与去标签正文,适合做网页内容的结构化提取。
Inputs: url (required), timeoutMs.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a clearly distinct operation: travel ranking, TC3 signing, text chunking, date math, read-only SQLite queries, web extraction, JWT decoding, and health checks. There is no functional overlap, so an agent can select the right tool from names alone.
All names use snake_case and follow a domain_action shape (date_calc, jwt_decode, webpage_extract, sqlite_query, health_ping). The only slight outlier is travel_hotspot_rank, which reads as a noun phrase with the verb at the end, but it remains readable and consistent in style.
Eight tools is a sensible size for a general-purpose utility toolkit and each tool covers a distinct capability. The set is a grab-bag rather than a cohesive domain, but the count itself is not excessive or thin.
Coverage is broad but shallow per utility: SQLite is read-only with no schema listing or writes, JWT supports decode/verify but not signing, and there are no generic JSON/string/HTTP-request helpers. For a "toolkit" these are acceptable but notable gaps that may force workarounds.
Maintenance
Related MCP Connectors
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Remote MCP for JSON repair, hashing, formatting, IDs, dates, units, and other small tools.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Related MCP Servers
- AlicenseDqualityDmaintenanceA foundation for building custom local Model Context Protocol (MCP) servers that provide tools accessible to AI assistants like Cursor or Claude Desktop.137MIT
- AlicenseCqualityDmaintenanceA Model Context Protocol server exposing 58 online tools (crypto, data, image, text, etc.) and workflow execution, enabling MCP clients like Claude Desktop to invoke them via natural language.588 npmMIT
- AlicenseAqualityDmaintenanceExposes a verified tool registry (calculator, sandboxed file read, web fetch) over MCP stdio, enabling any MCP-capable client to reuse the same tools from the inspectable ReAct loop.3MIT
- AlicenseNot gradedqualityBmaintenanceEnables developers to expose a single set of tool definitions as MCP server tools over stdio or Streamable HTTP, so Claude Code, Codex, Claude Desktop and Cursor can call them with risk-based annotations, human-approved irreversible writes, typed structured results and long-running job handling built in. It also ships the same tools as a CLI from one source, keeping both surfaces in parity.869 npmApache 2.0