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

> Discover how Reasonix efficiently resolves @ references for files, directories, and MCP resources using specialized pipelines for seamless integration. Learn more today!

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: how-to-guide
- Published: 2026-06-27

---

**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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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.

```typescript
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.

```typescript
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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.

```typescript
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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.

```typescript
// 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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/workers/accounts/src/routes/commands.ts) for server-side execution.
- The **@-menu** in [`desktop/frontend/src/lib/atMatches.ts`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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.