Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
fix(prompt): CreateDocument can't link docs correctly over MCP (#5067)
Eric Hayes673e835eaffb
diff --git a/crates/prompt/src/document_content_links.rs b/crates/prompt/src/document_content_links.rsnew file mode 100644index 0000000000..b8376299a1--- /dev/null+++ b/crates/prompt/src/document_content_links.rs@@ -0,0 +1,41 @@+//! MCP-only restatement of the document-content mention rule.+//!+//! The full Markdown-surface scope and `<m-document-mention>` tag rules live in+//! [`crate::mentions`], and already cover `CreateDocument`/`EditDocument`+//! content for in-app tool calls — [`crate::mentions`] composes into+//! [`crate::TOOL_USE_PROMPT`] via [`crate::BASE_PROMPT`], so nothing here is+//! needed there. But [`crate::mentions`] is deliberately excluded from the MCP+//! static instructions (see `MCP_STATIC_INSTRUCTIONS` in `lib.rs` and+//! [`crate::mcp_item_links`], which tells the model to link items in its own+//! MCP chat replies as plain Markdown URLs instead, since MCP clients can't+//! render the tag). This section exists solely to carry the document-content+//! mention rule into that MCP composition — without it, a document authored+//! over MCP would have no mention-tag rule to follow at all.+//!+//! It repeats the document-mention tag shape from [`crate::mentions`] rather+//! than importing it, so the two sections stay independently self-contained+//! even though they're composed into different prompts; `lib.rs`'s tests+//! assert the two occurrences don't diverge.++use crate::types::StaticPrompt;++static TITLE: &str = "Linking Macro items inside document content";++static INSTRUCTIONS: &str = r##"`CreateDocument` content (the `fileContent` argument) is rendered with the same Markdown parser used for chat responses, channel messages, and email bodies inside the Macro app — but only for Markdown (`.md`) documents. Non-Markdown documents (e.g. PDF, CSV, PNG, XLSX, DOCX, created by passing a non-`md` `file_extension`) are stored as raw file bytes and must never contain Markdown syntax or mention tags.++For Markdown document content, link to other Macro documents, channels, chats, projects, tasks, or email threads using `<m-document-mention>` XML mention tags, e.g.:++`<m-document-mention>{"documentId":"{id}","documentName":"","blockName":"md","blockParams":{}}</m-document-mention>`++This holds true even when `CreateDocument` is called through the MCP server, where you are otherwise told to link items in your own chat replies as plain Markdown URLs — that rule is about your conversational responses to the MCP client, not about content you write into a Macro document. Do NOT use plain Markdown links or bare URLs to reference other Macro items inside document content; only `<m-document-mention>` tags render as working links there.++The same applies to `EditDocument`: when its `instructions` ask for a mention or document-card, include the referenced item's id and name so the editing worker can construct the correct in-app markup itself.+"##;++static INTENT: &str = "Content written into Markdown documents via CreateDocument or EditDocument \+links other Macro items with `<m-document-mention>` XML tags — never plain Markdown URLs — \+regardless of whether the tool call arrived in-app or over MCP, while non-Markdown documents carry \+no Markdown syntax or mention tags at all.";++/// The document-content linking prompt.+pub static PROMPT: StaticPrompt<'static> = StaticPrompt::borrowed(TITLE, INSTRUCTIONS, INTENT);diff --git a/crates/prompt/src/lib.rs b/crates/prompt/src/lib.rsindex 86df068d2e..137b8e1dfa 100644--- a/crates/prompt/src/lib.rs+++ b/crates/prompt/src/lib.rs@@ -10,6 +10,7 @@ pub mod channel_mention;pub mod citations;pub mod connected_toolsets;pub mod do_not;+pub mod document_content_links;pub mod email;pub mod math;pub mod mcp_item_links;@@ -29,32 +30,45 @@ pub static BASE_PROMPT: ComposedPrompt = tone::PROMPT.compose(&do_not::PROMPT).compose(&about_macro::PROMPT);-/// The tool-enabled prompt: [`BASE_PROMPT`] with the tool use instructions and-/// email inbox behavior appended.+/// The tool-enabled prompt: [`BASE_PROMPT`] with the tool use instructions,+/// document-content linking rules, and email inbox behavior appended.pub static TOOL_USE_PROMPT: ComposedPrompt = BASE_PROMPT.compose(&tool_usage::PROMPT)+ .compose(&document_content_links::PROMPT).compose(&email::PROMPT);-/// Citation, do-not, and Macro-terms rules surfaced to external MCP clients,-/// composed together. These are static; the item-linking rules are not, because-/// they depend on the runtime app base URL — see [`mcp_instructions`].+/// Citation, do-not, Macro-terms, and document-content-linking rules surfaced+/// to external MCP clients, composed together. These are static; the+/// item-linking rules for the model's own replies are not, because they+/// depend on the runtime app base URL — see [`mcp_instructions`].////// Deliberately omits the in-app [`mentions`] section (MCP clients cannot render-/// `<m-document-mention>` tags) as well as chat tone/style and tool-use-/// instructions, which belong to the host client, not to Macro.+/// `<m-document-mention>` tags in a chat reply) as well as chat tone/style and+/// general tool-use instructions, which belong to the host client, not to Macro.+/// [`document_content_links`] is the exception: it still applies over MCP+/// because it governs content written *into* a Markdown document (via+/// `CreateDocument`/`EditDocument`), not the model's chat replies. See+/// [`mentions`] for the full statement of which surfaces (replies, channel+/// messages, email bodies, and Markdown documents) these Markdown/mention+/// rules cover.static MCP_STATIC_INSTRUCTIONS: ComposedPrompt = citations::PROMPT.compose(&do_not::PROMPT)- .compose(&about_macro::PROMPT);+ .compose(&about_macro::PROMPT)+ .compose(&document_content_links::PROMPT);/// Builds the instructions surfaced to external MCP clients via the server/// `instructions` field.////// Carries the formatting/correctness rules Macro features depend on so that AI-/// used through MCP produces valid output. Item links are rendered as plain-/// Markdown URLs (built from `base_url`, the runtime `APP_BASE_URL` value) and-/// lists of items as Markdown tables — NOT the in-app `<m-document-mention>`-/// markup, which MCP clients cannot render. `base_url` should already have any-/// trailing slash trimmed.+/// used through MCP produces valid output. Item links in the model's own chat+/// replies are rendered as plain Markdown URLs (built from `base_url`, the+/// runtime `APP_BASE_URL` value) and lists of items as Markdown tables — NOT+/// the in-app `<m-document-mention>` markup, which MCP clients cannot render.+/// Content the model writes *into* a Macro document via `CreateDocument` or+/// `EditDocument` is the opposite: it must still use `<m-document-mention>`+/// tags (see [`document_content_links`]), since the Macro app renders that+/// content regardless of which surface created it. `base_url` should already+/// have any trailing slash trimmed.pub fn mcp_instructions(base_url: &str) -> String {format!("{}\n{MCP_STATIC_INSTRUCTIONS}",@@ -100,4 +114,61 @@ mod tests {);}}++ #[test]+ fn mcp_instructions_still_require_mention_tags_inside_document_content() {+ let instructions = mcp_instructions("https://macro.com");++ // Even though the model's own MCP replies must use plain URLs, content+ // written into a Macro document via CreateDocument/EditDocument must+ // still use `<m-document-mention>` tags — the fix for the "CreateDocument+ // over MCP can't link docs correctly" bug.+ assert!(instructions.contains("CreateDocument"));+ assert!(instructions.contains(+ r#"<m-document-mention>{"documentId":"{id}","documentName":"","blockName":"md","blockParams":{}}</m-document-mention>"#+ ));++ // The plain-URL rule and the mention-tag rule must not silently+ // contradict each other: the plain-URL section explicitly scopes+ // itself to the model's own replies, not to document content.+ assert!(instructions.contains("does NOT apply to content you write into a Macro document"));+ }++ #[test]+ fn tool_use_prompt_also_carries_document_content_link_rules() {+ // The in-app prompt should keep the same guidance so behavior doesn't+ // diverge between surfaces.+ let in_app = TOOL_USE_PROMPT.to_string();+ assert!(in_app.contains("CreateDocument"));+ assert!(in_app.contains(+ r#"<m-document-mention>{"documentId":"{id}","documentName":"","blockName":"md","blockParams":{}}</m-document-mention>"#+ ));+ }++ #[test]+ fn mentions_and_document_content_links_share_an_identical_document_mention_tag() {+ // document_content_links deliberately repeats this tag literal (rather+ // than importing it) so it stays self-contained for MCP composition,+ // where `mentions` is excluded. Guard against the two silently+ // diverging by requiring both to contain the exact same string.+ const TAG: &str = r#"<m-document-mention>{"documentId":"{id}","documentName":"","blockName":"md","blockParams":{}}</m-document-mention>"#;+ assert!(mentions::PROMPT.instructions.contains(TAG));+ assert!(document_content_links::PROMPT.instructions.contains(TAG));+ }++ #[test]+ fn markdown_surface_scope_names_every_surface_but_the_reply_tone_exception() {+ // The mention rule must name every Markdown-authoring surface and the+ // non-Markdown-document exception, and the tool-use tone rule must not+ // silently bleed into tool-authored content.+ let in_app = TOOL_USE_PROMPT.to_string();+ for surface in ["SendChannelMessage", "SendEmail", "CreateDocument"] {+ assert!(+ in_app.contains(surface),+ "markdown surface scope should name {surface}"+ );+ }+ assert!(in_app.contains("non-Markdown documents"));+ assert!(in_app.contains("apply to your own conversational replies only"));+ }}diff --git a/crates/prompt/src/mcp_item_links.rs b/crates/prompt/src/mcp_item_links.rsindex c5c62a2989..3d285bfafc 100644--- a/crates/prompt/src/mcp_item_links.rs+++ b/crates/prompt/src/mcp_item_links.rs@@ -1,10 +1,18 @@-//! Rules for linking to Macro items in responses sent to external MCP clients.+//! Rules for linking to Macro items in the model's own *conversational+//! replies* sent to external MCP clients.//!//! Unlike the in-app [`crate::mentions`] section — which tells the model to emit//! `<m-document-mention>` XML tags that only render inside the Macro app — MCP//! responses are rendered by third-party clients that cannot resolve that-//! markup. So over MCP the model must link items as plain Markdown URLs built-//! from the app base URL, and list multiple items as a Markdown table.+//! markup. So over MCP the model must link items in its own replies as plain+//! Markdown URLs built from the app base URL, and list multiple items as a+//! Markdown table.+//!+//! This is scoped to the model's chat replies only. It does not govern content+//! the model writes *into* a Macro document (e.g. via `CreateDocument` or+//! `EditDocument`) — see [`crate::document_content_links`] for that, which+//! still requires `<m-document-mention>` tags even over MCP, since that content+//! is rendered by the Macro app itself, not by the MCP client.//!//! The base URL is only known at runtime (from `APP_BASE_URL`), so this section//! is rendered by [`render`] rather than declared as a `'static` prompt.@@ -28,8 +36,15 @@ pub fn render(base_url: &str) -> String {Do NOT emit `<m-document-mention>` XML tags or any other Macro internal \mention/markup format in these responses. Those only render inside the \Macro app and appear as raw text to MCP clients. This rule overrides any \- other instruction about mention tags: over MCP, always link items with \- plain Markdown URLs, never mention tags.\n\+ other instruction about mention tags for your own conversational \+ replies: over MCP, always link items in your chat responses with plain \+ Markdown URLs, never mention tags.\n\+ \n\+ This rule does NOT apply to content you write into a Macro document, \+ e.g. via the `CreateDocument` or `EditDocument` tools. That content is \+ rendered by the Macro app itself, not by this MCP client, so it must \+ still use `<m-document-mention>` tags to link correctly — see \"Linking \+ Macro items inside document content\" below.\n\\n\When you list multiple Macro items, present them as a Markdown table with \the columns `number`, `name`, and `link`, where `link` is the \diff --git a/crates/prompt/src/mentions.rs b/crates/prompt/src/mentions.rsindex 50f31afc13..e70ac4685c 100644--- a/crates/prompt/src/mentions.rs+++ b/crates/prompt/src/mentions.rs@@ -1,11 +1,26 @@-//! Rules for mentioning entities with XML mention tags.+//! Rules for mentioning entities with XML mention tags, and the scope of+//! Macro's shared Markdown rendering.+//!+//! These rules apply everywhere the model authors Markdown in Macro: its own+//! conversational replies, `SendChannelMessage` content, `SendEmail` bodies,+//! and `CreateDocument`/`EditDocument` content for Markdown (`.md`) documents.+//! The one exclusion is non-Markdown documents created via `CreateDocument`+//! (e.g. PDF, CSV, PNG, XLSX, DOCX) — those are stored as raw file bytes and+//! never parsed as Markdown, so they take no Markdown syntax or mention tags.+//!+//! See [`crate::document_content_links`] for the narrower restatement of the+//! document-mention tag that keeps it working over MCP, where this section is+//! deliberately excluded because MCP clients can't render the tag in a chat+//! reply (see [`crate::mcp_item_links`]).use crate::types::StaticPrompt;static TITLE: &str ="Mentioning documents, channels, channel messages, chats, projects, and email threads";-static INSTRUCTIONS: &str = r##"When referencing a document, channel, chat, project, or email thread, use XML mention tags with a JSON payload.+static INSTRUCTIONS: &str = r##"These rules apply everywhere you author Markdown in Macro: your own conversational replies, `SendChannelMessage` content, `SendEmail` bodies, and `CreateDocument`/`EditDocument` content for Markdown (`.md`) documents. They do NOT apply to non-Markdown documents created via `CreateDocument` (e.g. PDF, CSV, PNG, XLSX, DOCX) — those are raw file bytes, never parsed as Markdown, and must never contain mention tags or Markdown syntax.++When referencing a document, channel, chat, project, or email thread, use XML mention tags with a JSON payload.The AI does not need to know the name — an empty string is fine and the frontend will resolve it.- Document mention: `<m-document-mention>{"documentId":"{id}","documentName":"","blockName":"md","blockParams":{}}</m-document-mention>`@@ -27,7 +42,9 @@ If no inline or node ids are present:static INTENT: &str = "Entities and channel messages are referenced with correctly formatted \<m-document-mention> XML tags using the right blockName and blockParams for each entity type, \-including exactly \"email\" for email threads and channel_message_id for specific channel messages.";+including exactly \"email\" for email threads and channel_message_id for specific channel messages, \+across every Markdown surface (replies, channel messages, email bodies, and Markdown documents) — \+never inside non-Markdown documents.";/// The entity-mention prompt.pub static PROMPT: StaticPrompt<'static> = StaticPrompt::borrowed(TITLE, INSTRUCTIONS, INTENT);diff --git a/crates/prompt/src/tool_usage.rs b/crates/prompt/src/tool_usage.rsindex 7696d512be..52f59c2a4b 100644--- a/crates/prompt/src/tool_usage.rs+++ b/crates/prompt/src/tool_usage.rs@@ -6,6 +6,8 @@ static TITLE: &str = "Tool Use";static INSTRUCTIONS: &str = r##"## Tone and Style Additions+These apply to your own conversational replies only — not to Markdown you author via `CreateDocument`, `EditDocument`, `SendEmail`, or `SendChannelMessage`, which should use full Markdown formatting (headings, tables, bullet lists) appropriate to that surface.+- Write casual, text-message style prose- Avoid using formal formatting like bullet points, tables, and headings- Use short paragraphs@@ -41,7 +43,7 @@ when the user explicitely asks you to _execute_ code.(which creates a file for the code execution environment) for the `CreateDocument` tool which creates a document in theusers workspace. If the user asks you to create a document, write a code file, or create any file you should use the `CreateDocument` tool.-- `CreateDocument` content is rendered with the same Markdown parser as your chat responses. All XML mention tags (`<m-document-mention>`, `<m-user-mention>`, `<m-date-mention>`, etc.) and citation syntax (`[[uuid]]`, `[[md;...]]`) work identically inside created documents. Use them freely.+- `CreateDocument` content (for Markdown documents) is rendered with the same Markdown parser as your chat responses, channel messages, and email bodies, and citation syntax (`[[uuid]]`, `[[md;...]]`) works identically inside created documents. For linking to other Macro items from within that content, see the "Linking Macro items inside document content" rules. Non-Markdown documents (PDF, CSV, images, etc.) take raw content instead — no Markdown syntax or mention tags.## Tool usage patterns:@@ -68,7 +70,9 @@ users workspace. If the user asks you to create a document, write a code file, ostatic INTENT: &str = "The model proactively uses tools with precise filters instead of \claiming it lacks context, cites relevant tool results with mention tags, reserves code \execution for explicit requests, uses the SendEmail tool to draft or send emails instead of \-writing them inline in chat, and uses CreateDocument for files in the user's workspace.";+writing them inline in chat, uses CreateDocument for files in the user's workspace, and keeps its \+casual reply tone (short paragraphs, no formal formatting) scoped to its own conversational \+replies rather than to Markdown it authors via tools.";/// The tool-use prompt.pub static PROMPT: StaticPrompt<'static> = StaticPrompt::borrowed(TITLE, INSTRUCTIONS, INTENT);