MCP服务器模板

Deno MCP服务器模板

这些电池包括在TypeScript中构建生产MCP服务器的起点。

克隆，运行安装程序，开始构建。附带STDIO+HTTP传输、安全中间件、持久状态、沙盒执行、CI/CD工作流以及您需要的每种分发格式——JSR包、本机二进制文件、DXT扩展或托管在Deno Deploy上。

为什么是这个模板？

您将在2分钟内获得一个可用的MCP服务器。 不是玩具——一个真正的服务器，具有速率限制、CORS、会话管理、TLS支持和结构化日志记录功能。

Deno赋予你其他运行时所没有的超能力。 内置KV数据库（无需设置Postgres/Redis），本机cron调度，在microVM中执行沙盒代码，编译为二进制，以及一流的Deploy托管。此模板使所有这些都能工作。

船在任何地方，任何方式。 一个代码库产生：

• 用于Cursor、Claude Desktop或任何MCP客户端的本地STDIO服务器
• 具有流式HTTP传输的远程HTTP服务器
• 任何人都可以使用JSR包 deno run 不进行克隆
• 独立的本机二进制文件（无需运行时）
• 一键安装Claude Desktop的DXT扩展
• 一个用于托管云托管的Deno Deploy应用程序

AI代理友好的代码库。 小文件（<200 LOC），特征分组结构，显式类型。您的编码代理可以在不过载上下文的情况下导航和扩展它。

快速开始

# 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 — createApp 用于嵌入STDIO+HTTP主机而无需复制 main.ts.

看 .cursor/rules/project.mdc （建筑）适用于运输范围 McpServer 实例和共享上下文。

包含内容

开箱即用的基础设施

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

提示： review-code, language-snippet

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

工具： elicit-input, elicit-form-wizard （两步形式启发）， url-elicitation-demo （URL模式启发；仅限会话的流式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/ --注册MCP应用程序工具/资源(@modelcontextprotocol/ext-apps/server)添加交互式UI时
4. mcp-ui/ --MCP应用程序HTML的Vite捆绑包（运行 deno task build:mcp-ui；Deno安装npm deps并运行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应用程序） src/mcp/apps/ 加 mcp-ui/.更新相应的 mod.ts 桶出口和任何注册 src/mcp/mod.ts。完成。

HTTP安全

• 身份验证： 集 MCP_HTTP_BEARER_TOKEN （或 --http-bearer-token)因此，客户端必须发送 Authorization: Bearer … 或 x-api-key: … 上 /mcp对于CI或生产模板， MCP_REQUIRE_HTTP_AUTH=true 如果未设置令牌，则启动失败。路径下 /mcp-elicitation/ 故意跳过承载身份验证，这样普通的浏览器选项卡就可以在没有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和会话的请求使用较低的上限(RATE_LIMIT_UNKNOWN_CLIENT 在 src/shared/constants/http.ts).
• fetch-website-info: 默认情况下只允许使用公共HTTPS URL（阻止私有IP、localhost、链接本地、， .internal等等）。重定向后手动进行相同的检查。集 MCP_DOMAIN_TOOL_ALLOW_HTTP=1 允许 http:// 用于演示。支持MCP应用程序的主机可能会加载 ui://deno-mcp-template/fetch-website-info.html 用于内联UI；其他人仍然在工具结果中获得JSON文本。

看 .env.example 用于复制粘贴变量。

出货

选择您的发行版

平台特定的编译/DXT任务也可用： compile:win, compile:mac:arm64, compile:mac:x64, compile:linux:x64, compile:linux:arm64 （和匹配 dxt:* 变体）。

编译任务捆绑 static/ 目录，因此二进制文件提供静态路由，而不依赖于工作目录。

DXT先决条件： 使用以下命令安装DXT CLI一次 npm install -g @anthropic-ai/dxt.更新 static/dxt-manifest.json 在包装之前。

JSR先决条件： 你需要一个 JSR.io 账户如果您不打算在JSR上发布，请删除 .github/workflows/publish.yml.

客户端配置示例

工作室 （光标、克劳德桌面等）：

{
  "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 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

集 DENO_DEPLOY_TOKEN, DENO_DEPLOY_ORG，以及 DENO_DEPLOY_APP 在GitHub Actions secrets中自动部署。移除 .github/workflows/deploy.yml 如果不使用Deploy。

生产清单

• []运行 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 （格式、棉绒、类型检查、测试）

配置

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"

使用 --origin 完整的起源（例如。 https://example.com)以及 --host 用于主机名或IP（例如。 example.com, 127.0.0.1).

发展

deno task ci 跑 build:mcp-ui 首先，它只使用Deno下的install+Vite mcp-ui/ （参见 mcp-ui/README.md).CI只需要 德诺 对于这一步。

运行时权限

该应用程序在启动时验证所需的权限，并在可操作的指导下快速失败。对于生产，更喜欢显式权限而不是 -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/skills/ --实现工具、资源和提示的代理技能（见下文）
• .cursorignore --告诉Cursor除了 .gitignore
• .vscode/ --推荐的扩展名，默认格式为Deno
• .github/ --CI/CD工作流程、赞助商配置、问题模板
• CLAUDE.md --可选的Claude Code项目上下文
• CODE_OF_CONDUCT.md, CONTRIBUTING.md等等。--GitHub的社区管理文件

技能

这 .cursor/skills/ 目录包含代理技能，这些技能指导Cursor在此模板中实现MCP功能。每种技能都提供了文件模板、注册步骤、类型签名和工作示例。

这些技能在相关时由Cursor自动提取。让代理“添加新工具”或“创建资源”，它将遵循项目的模式。

参考文献

• MCP规范
• MCP应用程序/ @modelcontextprotocol/ext-apps （交互式工具UI）
• MCP概念
• Deno文档
• Deno部署
• Deno沙盒
• 荣誉

致谢

如果您使用此模板，请考虑贡献修复程序和功能，在仓库中担任主角，并赞助。

这不是Deno的官方项目。

许可证

麻省理工学院——这是一个模板，不是一个库。在交付生产之前，您需要对其进行修改。