Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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 the
users 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, o
static 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);