Encore 与 AI 工具集成实战：LLM 规则自动生成与本地 MCP Server 深度指南

Encore 与 AI 工具集成实战：LLM 规则自动生成与本地 MCP Server 深度指南

【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore

本指南系统讲解 Encore（Encore.ts / Encore Go）面向 AI 辅助开发的完整集成方案：如何通过encore llm-rules init为 Cursor、Claude Code、VS Code 等工具一键生成 LLM 规则与 MCP 配置，如何启动并连接 Encore 本地 MCP Server 让 AI 直接内省你的应用（服务、API、数据库、Trace），以及如何用真实基础设施（而非 Mock）驱动"生成代码 → 即时验证 → 分析 Trace → 迭代"的闭环。读完你将能够在自己的 Encore 项目中完整落地 AI 辅助后端开发工作流，并理解其底层 CLI 与守护进程实现。

Encore 从设计上就是为 AI 辅助开发而生的：声明式 API 与基础设施原语为 AI 提供了清晰的应用模型，Encore 专属的 LLM 规则文件与 MCP 集成让 AI 能够理解你的架构，并生成遵循既有模式、类型安全的代码。运行encore run即可启动应用，Encore 会自动在本地拉起数据库、Pub/Sub 等基础设施。生产环境则可通过自托管部署或 Encore Cloud 在你的 AWS / GCP 账号中供给基础设施。

AI 辅助开发能带来什么

Encore 的声明式 API 与基础设施原语（数据库、Pub/Sub、Cron、对象存储、缓存等）为 AI 提供了一个清晰、可推断的编程模型。在此基础上，AI 可以：

• 以内置护栏（guardrails）的方式为应用新增数据库、Pub/Sub Topic 等资源；
• 通过 MCP 内省你的应用——服务、API、数据库、Trace——从而给出准确且模式一致的代码建议。

也就是说，AI 不再是"猜着写代码"，而是先读取你应用的真实结构与运行时状态，再基于这些事实生成与现有模式一致的实现。

为项目启用 AI 支持的两种方式

方式一：使用 CLI（推荐）

新项目：执行encore app create时，CLI 会提示你选择一款 AI 工具（Cursor、Claude Code、VS Code、AGENTS.md、Zed），随后为所选工具生成对应的配置。从源码看，encore app create在创建应用后会直接调用llm_rules.SetupLLMRules(...)（见 cli/cmd/encore/app/create.go），并把创建好的应用 ID 一并写入 MCP 配置。

已有项目：在应用根目录执行encore llm-rules init：

encore llm-rules init

该命令会交互式地让你选择目标 AI 工具，并生成对应的配置文件（.cursorrules、CLAUDE.md等）。它同样支持非交互方式，通过-r/--llm-rules标志直接指定工具：

encore llm-rules init -r claudecode

命令底层（见 cli/cmd/encore/llm_rules/init.go）的执行流程如下：

1. 读取用户全局配置中的默认 LLM 工具（userconfig.Global().Get()的LLMRules字段），若未通过--llm-rules指定，则展示基于 Bubble Tea 的交互式选择列表；
2. 通过cmdutil.MaybeAppRoot()定位应用根目录，并解析根目录下的encore.app清单文件（pkg/appfile/appfile.go），据此判断语言是 TypeScript 还是 Go；
3. 调用SetupLLMRules(tool, lang, root, appID)写入规则文件与 MCP 配置；
4. 打印后续可直接复制使用的提示词建议。

支持的 AI 工具与生成的文件：源码 cli/cmd/encore/llm_rules/tool.go 中定义了 5 种受支持的工具（cursor、claudecode、vscode、agentsmd、zed）。各工具对应的生成内容如下：

几点值得注意的实现细节：

• 规则内容动态下载：SetupLLMRules会先调用downloadLLMInstructions(lang)，按语言从官方仓库拉取对应的 LLM 指令文本（TypeScript 为ts_llm_instructions.txt、Go 为go_llm_instructions.txt），然后写入上述规则文件。这两个文件的副本就在本仓库根目录，可以直接查看：ts_llm_instructions.txt、go_llm_instructions.txt。
• MCP 配置是"合并"而非"覆盖"：updateJsonFile会先读取目标文件（如.cursor/mcp.json）中已有的内容，再把encore-local追加进mcpServers，不会破坏你已有的其他 MCP 服务器配置。
• 规则文件"存在即跳过"：writeNewFileOrSkip对CLAUDE.md、AGENTS.md、.rules、copilot-instructions.md这类文件采用"已存在则跳过并给出黄色警告"的策略，避免覆盖你手写的自定义内容；而 Cursor 的encore.mdc因为是 Encore 专属配置文件，总是覆盖写入。
• 写入的 MCP 命令：无论哪个工具，写入的encore-local服务器命令都是encore mcp run --app=<你的应用ID>，应用 ID 来自encore.app中的 slug。

初始化完成后，CLI 还会打印一组可直接尝试的提示词，例如：

• "add image uploads to my hello world app"
• "add a SQL database for storing user profiles"
• "add a pub/sub topic for sending notifications"

方式二：使用 Encore Skills 包

Encore Skills 包可与 Cursor、Claude Code、GitHub Copilot 以及 10 余个其他 AI Agent 配合使用，安装方式：

npx add-skill encoredev/skills

也可以只安装特定技能或面向特定 Agent：

# 列出可用技能 npx add-skill encoredev/skills --list # 只安装到 Cursor 与 Claude Code npx add-skill encoredev/skills -a cursor -a claude-code

该技能包内含一个迁移技能（Migration Skill），可以把你的既有后端自动迁移到 Encore.ts。完整的迁移流程见 使用 AI Agent 迁移指南。

无论采用哪种方式，只要所选工具支持 MCP（Cursor、Claude Code 等），两条命令都会顺带完成 MCP 服务器配置。若想手动配置 MCP，见下文。

MCP Server：架构与两种传输方式

Encore 的 Model Context Protocol (MCP) 服务器为 AI Agent 提供对应用的深度内省能力：查询数据库、调用 API、检视服务、分析 Trace。它支持两种标准传输方式：

• SSE（Server-Sent Events）：适合交互式启动，可在终端观察连接信息；
• stdio：适合被 MCP 宿主（IDE、CLI Agent）以子进程方式拉起。

启动服务器

在 Encore 应用目录下执行：

encore mcp start

命令会打印类似下面的连接信息（源码见 cli/cmd/encore/mcp.go）：

MCP Service is running! MCP SSE URL: http://localhost:9900/sse?app=your-app-id MCP stdio Command: encore mcp run --app=your-app-id

把对应的 URL 或命令填进你的 MCP 宿主配置即可。使用 AI 工具期间请保持该命令运行。

命令参考

实现层面的关键事实（cli/cmd/encore/mcp.go）：

• 默认端口 9900：mcpPort常量默认为9900；
• 应用 ID 自动推断：未显式传入--app时，两个子命令都会回退到cmdutil.AppSlugOrLocalID()，从当前encore.app所在目录推断；
• stdio 是"桥接"而非独立服务：encore mcp run会先连接守护进程（daemon）暴露的 SSE 端点，然后充当翻译层——从 stdin 逐行读取 JSON-RPC 请求并转发，把来自 SSE 的响应打印到 stdout；
• 断线自动重连：SSE 连接断开后，sseConnection.reconnect以指数退避重试（初始 1s、上限 10s），期间未完成的请求会收到错误响应，保证 Agent 不会永久挂起。

守护进程端的 MCP 实现

真正的 MCP 服务器在 Encore 守护进程中实现（cli/daemon/mcp/mcp.go）：

• 工具注册：NewManager通过register*Tools()系列方法注册了 12 组工具，覆盖数据库、API、Trace、源码、Pub/Sub、对象存储、缓存、指标、Cron、密钥与文档；
• 服务器指令：一段精炼的serverInstructions会随initialize响应返回给模型，告诉它何时该用这些工具（例如"调用端点用call_endpoint而不是 curl"）；出于某些客户端（如 Claude Code 的 tool search）会截断 2KB 的限制，这段指令特意把最重要的引导放在最前面；
• 本地安全边界：originCheck中间件会拒绝所有携带Origin头的请求——因为本地代码 Agent（编辑器、CLI 工具）不会发送 Origin 头，而浏览器一定会发。这保证了 MCP 服务器只服务于本机 AI 工具，不会被网页滥用；
• 只读本地应用：该服务器只能看到本地encore run的应用；部署在云上的生产环境需要使用 Encore Cloud 的 MCP 服务器（同样可以通过claude mcp add --transport http encore-cloud https://api.encore.dev/mcp方式注册）。

连接 Cursor

手动配置：在项目根目录创建.cursor/mcp.json：

{ "mcpServers": { "encore-local": { "command": "encore", "args": ["mcp", "run", "--app=your-app-id"] } } }

你的应用 ID 可以在encore.app文件中找到（Encore.ts 应用的encore.app是一个 JSON 格式的文本清单文件）。

配置完成后，在 Cursor 的 Agent 模式中，你可以直接下达高级任务，例如：

"Add an endpoint that publishes to a pub/sub topic, call it and verify that the publish is in the traces"

连接 Claude Code

在 Encore 应用目录下执行：

claude mcp add --transport stdio encore-local -- encore mcp run --app=your-app-id

然后验证是否注册成功：

claude mcp list

列表中应能看到encore-local。--transport stdio意味着 Claude Code 会以子进程方式运行encore mcp run，通过标准输入/输出与 MCP 服务器通信。

AI 现在能做什么

接好 Skills 与 MCP 之后，AI 可以：

• 在代码中定义基础设施——声明数据库、Pub/Sub、Cron 任务、对象存储桶等原语；
• 生成类型安全的 API——产出遵循你既有模式、能通过校验的代码；
• 理解架构——通过 MCP 检视各服务及其连接关系；
• 查询数据库——内省 schema 与真实数据，生成准确的查询；
• 基于 Trace 调试——查看请求 Trace、各阶段耗时与 Span 细节，精准定位问题；
• 即时测试——运行encore run，用真实基础设施而非 Mock 进行验证。

实战一：基于分布式追踪的智能调试

AI 能通过 MCP 访问 Encore 的分布式追踪来智能排错。与其猜测，AI 可以直接查看真实请求 Trace、分析跨服务的耗时分布、检视每个 Span 的细节，从而精确定位问题出在哪一环。这形成了一条强大的反馈回路：生成代码 → 测试 → 分析 Trace → 迭代修复。

get_traces支持按服务、端点、Pub/Sub Topic/订阅、错误状态、时间范围、耗时与父 Trace ID 过滤，get_trace_spans则返回单个 Trace 的完整 Span 详情。两者配合（见 cli/daemon/mcp/trace_tools.go）即可完成"为什么上一个请求失败了"这类深度排查。

实战二：数据库内省

AI 可以通过query_database直接查询应用的真实数据库 schema 与数据，这意味着它理解你的真实数据模型，能够生成准确的查询、给出合理的 schema 变更建议，并通过检视实际记录来排查数据问题。相比"encore db conn-uri+ psql 手工往返"，一次调用即可对多个命名数据库批量执行多条 SQL。

实战三：用真实基础设施即时验证

当你运行encore run时，Encore 会在本地供给真实的数据库、Pub/Sub 等基础设施。AI 生成代码后可以立即对真实服务做验证，在部署之前就发现并修复问题。典型的示例提示词：

• "Add an endpoint that publishes to a pub/sub topic, call it and verify in traces"
• "Query the users database and show accounts created in the last week"
• "Create a new service with CRUD endpoints connected to PostgreSQL"

附：LLM 指令文件里到底有什么

写入各工具规则文件的内容源自在仓库根目录维护的 LLM 指令（ts_llm_instructions.txt 与 go_llm_instructions.txt）。它们不仅是风格指南，还包含大量实战约束：

• 语言与代码规范：如"必须编写有效的 TypeScript / Node.js v20+ 代码、使用 ES6+ 语法、内置fetch而非node-fetch"；
• 生成的目录勿手改：encore.gen/与.encore/由 CLI 重新生成，永远不要编辑；encore.app是文本清单文件（TS 为 JSON、Go 为 CUE 格式），可以像源码一样读取；
• MCP 使用策略：明确列出call_endpoint、query_database、get_traces、get_trace_spans、get_objects、search_docs/get_docs等"运行时工具"的完整参数与适用场景，并强调静态结构（服务、端点、Topic、schema）直接用源码搜索更快，不要滥用get_*工具；
• encore check快速验证：推荐用encore check取代"encore run+ 健康检查轮询 + curl"的手工流程，一条命令即可完成编译、启动、健康检查并执行内嵌的 curl DSL（路径必须相对、路径在首位、可用;串联多个请求）；
• Pub/Sub 验证技巧：订阅处理器的 Trace 与发布端点的 Trace 是两条独立根 Trace，验证时需要保留发布时的trace_id再用parent_trace_id过滤，并可轮询等待（间隔 250–500ms，上限约 10s）。

这些约束写进CLAUDE.md/encore.mdc之后，AI 生成的代码从一开始就会贴合 Encore 的约定，显著减少来回纠错。

MCP 工具全景

Encore 本地 MCP 服务器共暴露 20 个工具（全部带mcp__encore-local__前缀），AI 客户端在会话初始化时即可通过tools/list获取完整目录。按类别划分如下（完整说明见 docs/ts/cli/mcp.md）：

其中call_endpoint、query_database、get_traces、get_objects、search_docs/get_docs属于"运行时专属"工具——它们看到的是文件系统无法获得的实时数据，应优先于 shell 等价操作使用。

学习路径

• MCP Server 完整参考 —— 命令参考与全部暴露工具的说明
• 使用 AI Agent 迁移到 Encore.ts —— 借助 Skills 包的迁移技能自动迁移既有后端
• 快速开始指南 —— 构建你的第一个 Encore 应用
• Encore 原语概览 —— 数据库、Pub/Sub、Cron、对象存储等基础设施原语
• 自托管基础设施配置 与 CI/CD 部署 —— 生产环境部署方案（另可选择 Encore Cloud 在自有 AWS/GCP 账号中供给基础设施）

Encore 的 Skills 技能包与本地 MCP Server 共同构成了一个完整的 AI 开发闭环：规则文件让 AI 学会你的代码规范，MCP 让 AI 看见你的真实应用，本地基础设施让 AI 的每一次产出都能被即时验证。把这套工作流接入 Cursor 或 Claude Code，后端开发的"生成—验证—调试"循环将获得质的提升。

【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore