Deno MCP Template Repo

Deno MCP 服务模板

用于构建生产级 TypeScript MCP 服务的开箱即用起点。

克隆、运行设置，然后开始构建。内置 STDIO 和 HTTP 传输、安全中间件、持久化状态、沙盒执行、CI/CD 工作流，以及所需的所有分发格式——JSR 包、本机二进制文件、DXT 扩展，或托管在 Deno Deploy 上。

为什么选择此模板？

不到 2 分钟即可获得一个可运行的 MCP 服务。 这不是玩具项目，而是一个真正的服务，已配置速率限制、CORS、会话管理、TLS 支持和结构化日志记录。

Deno 为你提供其他运行时所没有的超能力。 内置 KV 数据库（无需配置 Postgres/Redis）、原生 cron 调度、在微型虚拟机中执行沙盒代码、编译为二进制文件，以及一流的 Deploy 托管支持。此模板充分利用了这些功能。

随处、随意部署。 一套代码可生成：

• 可供 Cursor、Claude Desktop 或任何 MCP 客户端使用的本地 STDIO 服务
• 使用 Streamable HTTP 传输的远程 HTTP 服务
• 任何人无需克隆即可通过 deno run 运行的 JSR 包
• 独立的本机二进制文件（无需运行时）
• 可一键安装到 Claude Desktop 的 DXT 扩展
• 用于托管云服务的 Deno Deploy 应用

适合 AI Agent 的代码库。 文件精简（<200 LOC）、按功能分组，并使用显式类型。你的编码 Agent 可以轻松浏览和扩展，不会遇到上下文过载。

快速开始

# Install Deno (if needed)
curl -fsSL https://deno.land/install.sh | sh

# Create your project from template
gh repo create my-mcp-server --template phughesmcr/deno-mcp-template
cd my-mcp-server

# One-time setup -- renames placeholders, then self-destructs
deno task setup

# Start the server (STDIO + HTTP on localhost:3001)
deno task start

# Or launch with MCP Inspector for interactive testing
deno task dev

从任何 MCP 客户端连接：

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "deno",
      "args": ["run", "-A", "/absolute/path/to/main.ts"]
    }
  }
}

完成。现在你拥有一个正在运行的 MCP 服务，其中包含工具、资源、提示词和任务工作流。

JSR 子路径导入

将此包发布到 JSR 后，你可以导入完整程序（main.ts）或更精简的入口点：

• jsr:@scope/name — 与 main.ts 相同（CLI 入口）。
• jsr:@scope/name/mcp — createMcpServer、mcpServerDefinition、上下文/订阅辅助函数及相关导出。处理请求前，宿主仍须打开 Deno KV（以及其他共享服务），与 createApp 的做法相同。
• jsr:@scope/name/app — 用于嵌入 STDIO + HTTP 宿主的 createApp，无需复制 main.ts。

传输范围内 McpServer 实例和共享上下文的相关说明，请参阅 .cursor/rules/project.mdc（架构）。

包含内容

开箱即用的基础设施

内容	方式	位置
双传输方式	单个应用同时支持 STDIO 和 Streamable HTTP	src/app/
HTTP 中间件	速率限制、CORS、可选的 bearer 身份验证（不应用于 /mcp-elicitation/* 浏览器页面）、安全标头、超时、会话	src/app/http/hono.ts
持久化状态	Deno KV——本地零配置，在 Deploy 上内置支持	src/kv/
会话恢复	基于 KV 的事件存储，用于流恢复	src/app/http/kvEventStore.ts
后台任务	MCP 实验性任务：KV TaskStore + TaskMessageQueue，以及用于延迟回显演示的 listenQueue worker	src/mcp/tasks/
定时任务	使用 Deno.cron 执行定期维护	src/app/cron.ts
沙盒执行	使用 @deno/sandbox microVM 执行不受信任的代码	src/mcp/tools/sandbox.ts
MCP Apps（交互式 UI）	示例工具 + 通过 @modelcontextprotocol/ext-apps 提供的 ui:// HTML 包	mcp-ui/、src/mcp/apps/、static/mcp-apps/
CI/CD 工作流	使用 GitHub Actions 实现 CI、发布、部署和 JSR 发布	.github/workflows/
配置管理	带验证与合并功能的 CLI 标志 + 环境变量	src/app/cli.ts
权限预检	快速失败的启动检查，并提供可操作的指导	src/app/permissions.ts

MCP 功能示例（替换为你自己的功能）

提示词： review-code、language-snippet

资源： hello://world、greetings://{name}、counter://value（由 KV 支持，可订阅）

工具： elicit-input、elicit-form-wizard（两步表单征询）、url-elicitation-demo（URL 模式征询；仅支持带会话的 Streamable HTTP）、fetch-website-info（文本 + 在支持的客户端中可选的 MCP Apps UI）、increment-counter、log-message、notify-list-changed、poem（采样）、execute-code（沙盒执行）

任务工作流（实验性）： delayed-echo、guided-poem（征询 + 采样流水线）

这些示例涵盖带参数的提示词、静态和动态资源、订阅、采样、表单和 URL 征询、通知、列表变更事件、KV 持久化、沙盒执行、异步任务模式，以及 MCP Apps UI 示例（fetch-website-info）。请将它们用作参考，然后替换为你的领域逻辑。

打造你自己的项目

首先运行 deno task setup——该命令会一次性重写整个项目中的包名称、作用域和元数据。

从哪里开始编辑

1. src/shared/constants/——服务名称、描述、版本、默认值
2. src/mcp/tools/——添加你的工具（遵循现有模式）
3. src/mcp/apps/——添加交互式 UI 时，注册 MCP App 工具/资源（@modelcontextprotocol/ext-apps/server）
4. mcp-ui/——MCP App HTML 的 Vite 包（运行 deno task build:mcp-ui；Deno 会安装 npm 依赖并运行 Vite——参见 mcp-ui/README.md）
5. src/mcp/resources/——添加你的资源
6. src/mcp/prompts/——添加你的提示词
7. src/mcp/serverDefinition.ts——功能列表、能力标志和派生的 SERVER_CAPABILITIES（从 src/shared/constants/mcp.ts 重新导出）
8. src/mcp/mod.ts——服务构建（注册顺序遵循定义）
9. src/app/http/hono.ts——调整 CORS、中间件和路由

要移除的内容

从 src/mcp/tools/、src/mcp/resources/、src/mcp/prompts/ 中删除不需要的示例文件；如果不使用 MCP Apps，也请删除 src/mcp/apps/ 和 mcp-ui/。更新相应的 mod.ts 汇总导出，以及 src/mcp/mod.ts 中的任何注册。完成。

HTTP 安全

• 身份验证： 设置 MCP_HTTP_BEARER_TOKEN（或 --http-bearer-token），要求客户端在 /mcp 上发送 Authorization: Bearer … 或 x-api-key: …。对于 CI 或生产环境模板，设置 MCP_REQUIRE_HTTP_AUTH=true 后，如果未设置令牌，启动将失败。/mcp-elicitation/ 下的路径有意跳过 Bearer 身份验证，以便普通浏览器标签页无需 MCP 令牌即可打开 URL 模式的引导页面。
• 链接的公开 URL： 在反向代理后，设置 MCP_PUBLIC_BASE_URL（或 --public-base-url）为用户在浏览器中访问的 https:// 源站，这样 URL 引导链接才能与部署地址一致。如果未设置，服务端会根据绑定地址推导 URL（参见 src/shared/publicBaseUrl.ts）。
• 暴露风险： 绑定到非回环主机名且未设置令牌时会记录警告：任何能够访问该端口的人都可以使用 MCP。请使用令牌，或在反向代理处终止 TLS 并进行身份验证。
• 所有网络接口： 监听 0.0.0.0 或 :: 需要设置 --dnsRebinding，并设置 --host / MCP_ALLOWED_HOSTS（启动时会进行验证）。
• CORS： 不允许使用通配符 * 来源；请列出明确的来源（例如 MCP_ALLOWED_ORIGINS）。
• 速率限制： 设置 MCP_TRUST_PROXY=true 后，限制会依据代理客户端 IP 标头（仅适用于可信的真实代理之后）。没有套接字 IP 且没有会话的请求会采用较低的上限（src/shared/constants/http.ts 中的 RATE_LIMIT_UNKNOWN_CLIENT）。
• fetch-website-info： 默认只允许公开的 HTTPS URL（会阻止私有 IP、localhost、链路本地地址、.internal 等）。重定向会在执行相同检查后手动跟随。设置 MCP_DOMAIN_TOOL_ALLOW_HTTP=1 可在演示时允许使用 http://。支持 MCP Apps 的主机可以加载 ui://deno-mcp-template/fetch-website-info.html 以显示内嵌 UI；其他主机仍会在工具结果中收到 JSON 文本。

复制粘贴所需的变量请参阅 .env.example。

发布

选择分发方式

目标	命令	输出
通过 STDIO 在本地运行	deno task start	直接进程
通过 HTTP 提供服务	deno task start	localhost:3001/mcp
发布为 JSR 包	deno publish	jsr:@scope/package
编译原生二进制文件	deno task compile:all	dist/server/
打包为 DXT	deno task dxt:all	dist/server.dxt
部署到云端	deno deploy --prod	Deno Deploy URL

还提供特定平台的编译/DXT 任务：compile:win、compile:mac:arm64、compile:mac:x64、compile:linux:x64、compile:linux:arm64（以及对应的 dxt:* 变体）。

编译任务会打包 static/ 目录，因此二进制文件无需依赖工作目录即可提供静态路由服务。

DXT 前置条件： 使用 npm install -g @anthropic-ai/dxt 一次性安装 DXT CLI。打包前请更新 static/dxt-manifest.json。

JSR 前置条件： 你需要一个 JSR.io 账户。如果不打算在 JSR 上发布，请移除 .github/workflows/publish.yml。

客户端配置示例

STDIO（Cursor、Claude Desktop 等）：

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "deno",
      "args": ["run", "-A", "/absolute/path/to/main.ts"]
    }
  }
}

使用 mcp-remote 的 HTTP：

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3001/mcp"]
    }
  }
}

直接使用 HTTP（支持 URL 的客户端）：

{
  "mcpServers": {
    "my-mcp-server": {
      "url": "http://localhost:3001/mcp",
      "headers": { "origin": "http://localhost:3001" }
    }
  }
}

JSR 包：

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "deno",
      "args": ["run", "-A", "jsr:@your-scope/your-package"]
    }
  }
}

编译后的二进制文件：

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "/absolute/path/to/binary"
    }
  }
}

Claude Code：

claude mcp add my-mcp-server /absolute/path/to/binary
claude mcp add --transport http my-mcp-server http://localhost:3001/mcp

部署到 Deno Deploy（可选）

# Create app (one-time)
deno deploy create \
  --org <YOUR_ORG> \
  --app <YOUR_APP> \
  --source local \
  --runtime-mode dynamic \
  --entrypoint main.ts \
  --build-timeout 5 \
  --build-memory-limit 1024 \
  --region us

# Deploy
deno deploy --prod

在 GitHub Actions secrets 中设置 DENO_DEPLOY_TOKEN、DENO_DEPLOY_ORG 和 DENO_DEPLOY_APP，以实现自动部署。如果不使用 Deploy，请移除 .github/workflows/deploy.yml。

生产环境检查清单

• 运行 deno task setup，并确认所有占位名称都已替换
• 移除或替换不会随产品发布的演示工具、资源和提示词
• 更新 static/.well-known/openapi.yaml 和 static/dxt-manifest.json
• 为你的环境配置 MCP_ALLOWED_ORIGINS 和 MCP_ALLOWED_HOSTS
• 将 src/app/http/kvEventStore.ts 替换为生产级事件存储（附带的实现仅用于演示）
• 生产环境中将 deno run -A 改为显式权限
• 检查 --allow-net 范围，确保涵盖所有出站工具调用
• 在 CI 和托管服务提供商中设置环境变量
• 运行 deno task ci（格式检查、lint、类型检查、测试）

配置

变量	标志	默认值	描述
MCP_NO_HTTP	--no-http	false	禁用 HTTP 服务
MCP_NO_STDIO	--no-stdio	false	禁用 STDIO 传输
MCP_HOSTNAME	-n	localhost	HTTP 监听主机名
MCP_PORT	-p	3001	HTTP 监听端口
MCP_PUBLIC_BASE_URL	--public-base-url		用于浏览器链接（URL 引导）的公开 http(s):// 源；末尾不要加斜杠
MCP_TLS_CERT	--tls-cert		PEM 证书路径（需要 --tls-key）
MCP_TLS_KEY	--tls-key		PEM 私钥路径（需要 --tls-cert）
MCP_HEADERS	-H		响应标头（集合）
MCP_JSON_RESPONSE	--json-response	false	仅返回 JSON 响应（禁用 SSE）
MCP_DNS_REBINDING	--dnsRebinding	false	启用传输层 Origin/Host 检查（绑定到环回地址时已进行 Host 验证）
MCP_ALLOWED_ORIGINS	--origin		允许的 CORS 源（集合）
MCP_ALLOWED_HOSTS	--host		允许的主机名（集合）
MCP_KV_PATH	--kv-path		自定义 Deno KV 数据库路径
MCP_MAX_TASK_TTL_MS	--max-task-ttl-ms	86400000（24h）	实验性 MCP 任务允许客户端请求的最大 TTL（毫秒）；在 KvTaskStore 中限制范围（最小 60s，最大 1y — 参见 src/shared/validation/config.ts）
DENO_DEPLOY_TOKEN			部署令牌（execute-code 沙箱工具必需）

CLI 标志会覆盖环境变量。集合值（-H、--origin、--host）会合并两种来源中的值。

集合配置示例

可在 .env 中将集合类型的值设为逗号分隔的字符串：

MCP_HEADERS=x-api-key:demo,cache-control:no-store
MCP_ALLOWED_ORIGINS=http://localhost:6274,https://app.example.com
MCP_ALLOWED_HOSTS=localhost,127.0.0.1,app.example.com

也可以重复指定 CLI 标志：

deno task start -- \
  -H "x-api-key:demo" \
  -H "cache-control:no-store" \
  --origin "http://localhost:6274" \
  --origin "https://app.example.com" \
  --host "localhost" \
  --host "app.example.com"

完整源（例如 https://example.com）使用 --origin；主机名或 IP（例如 example.com、127.0.0.1）使用 --host。

开发

命令	作用
deno task start	启动服务
deno task dev	使用 MCP Inspector 和监视模式启动
deno task build:mcp-ui	将 MCP App HTML 构建到 static/mcp-apps/（Deno + mcp-ui/deno.lock；无需 Node.js）
deno task ci	先运行 build:mcp-ui，然后进行格式检查、lint、类型检查和测试
deno task test:integration	运行集成测试
deno task test:coverage	运行测试并生成覆盖率报告
deno task bench	运行基准测试

deno task ci 会先运行 build:mcp-ui，该任务在 mcp-ui/ 下使用仅限 Deno 的安装方式和 Vite（参见 mcp-ui/README.md）。CI 在此步骤中只需要 Deno。

运行时权限

应用会在启动时验证所需权限，并在验证失败时立即提供可执行的指导。生产环境中，优先使用显式权限，而不是 -A：

# HTTP + STDIO (local defaults)
deno run --env-file=.env \
  --allow-env --allow-read --allow-write --allow-sys \
  --allow-net=localhost:3001 \
  main.ts

# STDIO only (no HTTP listener)
deno run --env-file=.env \
  --allow-env --allow-read --allow-write --allow-sys \
  main.ts --no-http

如果保留联网工具（例如 fetch-website-info），请将其目标地址加入 --allow-net。

锁文件与可复现性

此模板会跟踪 deno.lock，以确保依赖解析结果确定。

• 刷新锁定数据：deno install --entrypoint main.ts --frozen=false
• 验证锁定的依赖解析结果（CI）：deno install --frozen --entrypoint main.ts
• 更改依赖时，提交 deno.lock。

项目结构

main.ts                     # Entry point
src/
  app/                      # Runtime shell: transports, HTTP, KV, cron, signals
  mcp/                      # MCP server: tools, resources, prompts, tasks, apps
  shared/                   # Constants, types, validation, utilities
mcp-ui/                     # Vite + ext-apps front-end for MCP App HTML bundles
static/                     # Static files, OpenAPI spec, DXT manifest, mcp-apps/*.html
scripts/                    # Setup, build, and packaging helpers
test/                       # Integration tests and benchmarks
.github/workflows/          # CI, release, deploy, publish

如需查看带注释的源代码树、传输内部实现和开发注意事项，请参阅 .cursor/rules/project.mdc。

额外内容

附带的实用文件：

• .cursor/rules/ -- 本项目的 Cursor Agent 规则
• .cursor/skills/ -- 用于实现工具、资源和提示词的 Agent 技能（见下文）
• .cursorignore -- 告诉 Cursor 除 .gitignore 外还要排除哪些文件
• .vscode/ -- 推荐的扩展，以及设为默认格式化程序的 Deno
• .github/ -- CI/CD 工作流、赞助者配置、问题模板
• CLAUDE.md -- 可选的 Claude Code 项目上下文
• CODE_OF_CONDUCT.md、CONTRIBUTING.md 等 -- GitHub 社区管理文件

技能

.cursor/skills/ 目录包含指导 Cursor 在此模板中实现 MCP 功能的 Agent 技能。每项技能都提供文件模板、注册步骤、类型签名和可运行示例。

技能	涵盖内容
implementing-mcp-tools	标准工具、采样、表单和 URL 引导、资源支持的工具、通知
implementing-mcp-resources	静态资源、KV 支持的资源、资源模板、订阅
implementing-mcp-prompts	使用静态参数或动态补全的提示词

当相关时，Cursor 会自动选用这些技能。让 Agent“添加一个新工具”或“创建一个资源”，它就会遵循项目的模式。

参考资料

• MCP 规范
• MCP Apps / @modelcontextprotocol/ext-apps（交互式工具界面）
• MCP 概念
• Deno 文档
• Deno Deploy
• Deno Sandbox
• Hono

致谢

如果你使用了此模板，请考虑贡献修复和功能、为仓库点星并赞助。

这不是 Deno 官方项目。

许可证

MIT -- 这是一个模板，而非库。发布到生产环境前，请按需修改。