How Reasonix Resolves @ References for Files, Directories, and MCP Resources

Reasonix resolves "@" tokens through three specialized pipelines—workspace paths parsed by parseWorkspaceReference, attachment files transformed via replaceAttachmentRefsForDisplay, and MCP commands routed through the @modelcontextprotocol/ interface to the backend commands API.

The DeepSeek-Reasonix repository implements a unified "@" syntax that serves as a shortcut for referencing local workspace assets, hidden attachment files, and remote Model-Context-Protocol (MCP) resources. Understanding how these @ references are parsed and resolved reveals the architecture behind the Composer's intelligent resource linking system.

Workspace File and Directory References

The frontend handles workspace references through utilities in desktop/frontend/src/lib/workspaceDrag.ts. When a user drags a file or folder into the Composer, the system generates a token that starts with "@" and includes the relative path from the project root.

Formatting References with formatWorkspaceReference

The formatWorkspaceReference function creates the string representation used throughout the UI. For directories, it appends a trailing slash to distinguish them from files.

import { formatWorkspaceReference } from "./workspaceDrag";

const fileRef = formatWorkspaceReference("src/utils/helpers.ts");
// Returns: "@src/utils/helpers.ts"

const dirRef = formatWorkspaceReference("src/components", true);
// Returns: "@src/components/"

Parsing References with parseWorkspaceReference

When processing user input or drop events, parseWorkspaceReference extracts the path using the regex /^@(\S+)$/. It returns a payload object containing the path string and an isDir boolean flag.

import { parseWorkspaceReference } from "./workspaceDrag";

const payload = parseWorkspaceReference("@src/components/");
// Returns: { path: "src/components/", isDir: true }

Attachment File References

Files stored in the hidden .reasonix/attachments directory use a different resolution path. The system maintains two representations: a display-friendly markdown link for the UI and a raw path string for backend submission.

Converting Between Display and Submit Formats

In desktop/frontend/src/lib/attachmentDisplay.ts, the replaceAttachmentRefsForDisplay function transforms raw tokens into markdown links for the Composer interface. Conversely, restoreAttachmentRefsForSubmit reverts the display format back to the raw "@" token before transmission.

The regex referenceRefRe = /(^|\s)@([^\s]+)/g identifies attachment tokens that are not part of URLs.

import { 
  replaceAttachmentRefsForDisplay, 
  restoreAttachmentRefsForSubmit 
} from "./attachmentDisplay";

// For display in the Composer
const display = replaceAttachmentRefsForDisplay(
  "See diagram @.reasonix/attachments/flow.png"
);
// Returns: "See diagram @[flow.png](.reasonix/attachments/flow.png)"

// For submission to backend
const submit = restoreAttachmentRefsForSubmit(display);
// Returns: "See diagram @.reasonix/attachments/flow.png"

MCP Resource Resolution

Reasonix treats tokens matching @modelcontextprotocol/<package> as executable commands rather than file paths. This enables dynamic integration with external MCP servers directly from the chat interface.

The @modelcontextprotocol/ Prefix

When a user references a package like @modelcontextprotocol/server-github, the Composer recognizes the modelcontextprotocol namespace and treats the token as a command. Unlike workspace or attachment references, these bypass the file system entirely and trigger remote execution.

Backend Execution via Commands API

The backend route in workers/accounts/src/routes/commands.ts receives the command string and forwards it to the MCP service. The server executes the requested package (typically via npx -y @modelcontextprotocol/server-github) and returns the results.

// Example MCP command issued from chat
const command = "npx -y @modelcontextprotocol/server-github";
// This is sent to the backend API endpoint for execution

The @-Menu Resolution Flow

The resolution process begins when a user types "@" in the Composer. The @-menu component, implemented in desktop/frontend/src/lib/atMatches.ts, filters available candidates based on the current token context.

Upon submission, the system routes the reference through one of three distinct pipelines:

• Workspace paths → parseWorkspaceReference → workspace reference payload to /api/workspace/reference
• Attachments → restoreAttachmentRefsForSubmit → raw @.reasonix/attachments/... string
• MCP commands → @modelcontextprotocol/ prefix detected → routed to /api/mcp/execute

Summary

• Workspace references use formatWorkspaceReference and parseWorkspaceReference in desktop/frontend/src/lib/workspaceDrag.ts to handle file and directory paths with optional trailing slash detection.
• Attachment references rely on regex matching in desktop/frontend/src/lib/attachmentDisplay.ts to convert between display markdown and raw submission formats for files stored in .reasonix/attachments.
• MCP resources bypass local file resolution entirely, instead routing @modelcontextprotocol/ prefixed commands through workers/accounts/src/routes/commands.ts for server-side execution.
• The @-menu in desktop/frontend/src/lib/atMatches.ts provides the frontend filtering mechanism that initiates all three resolution types.

Frequently Asked Questions

What regex pattern does Reasonix use to identify attachment references?

Reasonix uses referenceRefRe = /(^|\s)@([^\s]+)/g defined in desktop/frontend/src/lib/attachmentDisplay.ts. This pattern captures any "@" token that is not part of a URL, allowing the system to distinguish attachment references from other text.

How does Reasonix distinguish between a file and directory in workspace references?

The system checks for a trailing slash in the reference string. When formatWorkspaceReference is called with isDir: true, it appends a slash. The parseWorkspaceReference function returns an isDir boolean flag based on this suffix, enabling the backend to handle folders differently from individual files.

Where are MCP commands processed in the Reasonix backend?

MCP commands are processed in workers/accounts/src/routes/commands.ts. This endpoint receives payloads containing @modelcontextprotocol/ prefixed strings and coordinates with the MCP worker to execute the requested package remotely.

Can custom MCP servers be referenced using the @ syntax?

Yes. Any package following the @modelcontextprotocol/ naming convention can be referenced. The Composer sends these tokens to the backend commands API, which executes them via npx, allowing users to invoke both official and custom MCP servers from within the chat interface.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}