Notes

每个服务都位于 servers/ 下的独立文件夹中，并作为独立的软件包发布到 npm，同时通过 npm 工作区共享工具。可将它们连接到任意 MCP 客户端，包括 Claude Desktop、Claude Code、Cursor 等。

目录

• 服务
• 快速开始
• 安装
• 连接到客户端
• 架构与约定
• 开发
• 添加新服务
• 发布
• 贡献
• 许可证

服务

服务	描述	状态
notes	本地 Markdown 笔记：排序后的全文和语义搜索、标签、待办事项、[[wiki-link]] 知识图谱、每日笔记和模板，以及斜杠命令工作流（提示词）	✅ 稳定
files	沙盒化本地文件系统：读取、glob 与内容搜索、节省令牌的编辑、复制/移动、软删除回收站、zip、校验和及去重	✅ 稳定
github	GitHub：搜索仓库/代码/议题，读取仓库/议题/PR/文件，管理通知、创建议题 — 通过 OAuth 设备流程或令牌进行身份验证	✅ 稳定
git	Git：状态、日志、差异、文件历史、分支/标签、受控暂存/提交，以及远程克隆/获取/拉取/推送 — 纯 JavaScript，无需 git 二进制文件	✅ 稳定
sql	SQL 数据库：对 Postgres 和 SQLite 执行只读查询并检查架构，受控写入	✅ 稳定
http	HTTP/REST 客户端：临时请求和已保存的集合/环境、环境密钥、主机白名单及 SSRF 防护	✅ 稳定

更多功能即将推出：Spotify 控制器及其他功能。

快速开始

git clone https://github.com/Abhishekkumar2021/mcp-suite.git
cd mcp-suite
npm install      # installs deps for every workspace
npm run build    # builds every server

安装

每个服务都通过所有常见渠道发布。对于 Claude Code 插件，只需添加一次 marketplace — /plugin marketplace add Abhishekkumar2021/mcp-suite — 然后按表格安装。完整配置请参阅各服务的 README。

服务	Claude Code 插件	npm（任意客户端）	Claude Desktop（MCPB）	MCP registry
notes	/plugin install notes	npx -y @abhishekmcp/notes	从最新版本拖入 notes-*.mcpb	io.github.Abhishekkumar2021/notes
files	/plugin install files	npx -y @abhishekmcp/files	拖入 files-*.mcpb	io.github.Abhishekkumar2021/files
github	/plugin install github	npx -y @abhishekmcp/github	拖入 github-*.mcpb	io.github.Abhishekkumar2021/github
git	/plugin install git	npx -y @abhishekmcp/git	拖入 git-*.mcpb	io.github.Abhishekkumar2021/git
sql	/plugin install sql	npx -y @abhishekmcp/sql	拖入 sql-*.mcpb	io.github.Abhishekkumar2021/sql
http	/plugin install http	npx -y @abhishekmcp/http	拖入 http-*.mcpb	io.github.Abhishekkumar2021/http

notes 默认使用 ~/notes；files 必须设置 FS_ROOTS（它可以访问的目录）。MCPB bundle 通过 Claude Desktop → Settings → Extensions 安装。

连接到客户端

各服务的 README 都提供了完整的配置说明。以下以在 Claude Code 中使用 notes 服务为例：

claude mcp add notes --env NOTES_DIR=$HOME/notes -- node "$(pwd)/servers/notes/dist/index.js"

或在 Claude Desktop 中使用（claude_desktop_config.json）：

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-suite/servers/notes/dist/index.js"],
      "env": { "NOTES_DIR": "/absolute/path/to/your/notes" }
    }
  }
}

架构与约定

所有服务都遵循以下原则：

• 默认采用纯 JS/WASM；仅在确有需要时使用原生依赖。 服务通过 npx/MCPB 在任何机器上运行，因此强烈优先采用可移植的纯 JS/WebAssembly；只有确有需要时才使用原生依赖（并进行限制且记录说明）。实际上，这些服务的依赖都很轻量：notes 使用 MiniSearch + WebAssembly embeddings，sql 使用 sql.js WASM SQLite 引擎，files 使用 fast-glob 代替 ripgrep。npm audit 检查结果始终干净。
• 沙箱优先，分层设计。 每个服务都以精简的 index.ts（仅注册工具）作为入口，依托职责明确的模块；所有路径都必须通过同一安全边界（realpath 包含性检查、拒绝符号链接逃逸、原子写入）。
• 默认节省 token。 分页、读取头部/尾部/指定章节、摘要片段和精简的图引用都能减少工具输出。
• 自动化、无需人工介入的发布。 使用 <server>-v<version> 标记的 GitHub Release 会发布到 npm（带 provenance）、官方 MCP registry，并附加 MCPB bundle — 全部通过 OIDC 完成，无需密钥。
• 在 CI 中测试。 每个服务都包含已提交的 node:test 测试套件（单元测试 + 集成/安全测试），并在每次推送时运行。

开发

这是一个 npm workspaces monorepo。

npm install                      # install all workspace dependencies (run once at the root)
npm run build                    # build every server
npm run build -w servers/notes   # build a single server
npm test --workspaces --if-present  # run each server's test suite
npm run clean                    # remove all build output

添加新服务

1. 创建 servers/<name>/，其中包含独立的 package.json（npm name 必须唯一）和 tsconfig.json，并设置 extends: "../../tsconfig.base.json"。
2. 将源代码放入 servers/<name>/src/。
3. 在根目录运行 npm install，以将其纳入 workspace。
4. 在上方的 服务 表格中添加一行。

所有服务都遵循命名标准（@abhishekmcp/<slug>）。详细指南请参阅 CONTRIBUTING.md。

发布

发布流程已自动化。创建一个使用 <server>-v<version> 标记的 GitHub Release 会触发 publish.yml，该工作流完全通过 GitHub OIDC 进行身份验证（无需 NPM_TOKEN），会将软件包发布到 带 provenance 的 npm、注册到官方 MCP registry，并构建 MCPB bundle 并将其附加到该版本。

# bump servers/<name>/package.json, commit, then:
gh release create <name>-v<version> --title "<name> v<version>" --notes "…"

贡献

欢迎贡献！请阅读 CONTRIBUTING.md 和我们的 行为准则。发现安全问题？请参阅 SECURITY.md。

许可证

MIT © Abhishek