office mcp architecture

Office MCP Server Architecture: Hybrid Document Management

Overview

The Office MCP server now supports a hybrid architecture that allows it to work both as:

1. A generic standalone MCP service (for Cursor, Claude Desktop, etc.)
2. An integrated service with shared storage (for the Supen app)

This design keeps the MCP server generic and reusable while optimizing for local scenarios.

Two Operational Modes

1. Shared Storage Mode (Local/Same-Server)

When the Office MCP server and app run on the same machine or have access to the same filesystem:

// App side - document-bridge.ts
const bridge = await createDocumentBridge(workspaceId, {
  mode: 'shared',
  mcpTransport: 'stdio',
  command: 'dotnet',
  args: ['run', '--workspace', 'mcp-servers/office/OfficeMcp.csproj']
});

// Documents are stored in: .vibex/workspaces/{workspaceId}/documents/
// Both app and MCP server can directly access these files

Environment Variables for Shared Mode:

VIBEX_STORAGE_PATH=../../.vibex/workspaces
VIBEX_PROJECT_ID=default

Advantages:

• No file uploads needed between tool calls
• Direct file access for both app and MCP server
• Lower latency and bandwidth usage
• Simpler workflow for local development

2. Upload Mode (Remote/Distributed)

When the Office MCP server runs on a different server:

// App side - document-bridge.ts
const bridge = await createDocumentBridge(workspaceId, {
  mode: 'upload',
  mcpServerUrl: 'https://mcp-server.example.com',
  sessionId: 'unique-session-id'
});

// Documents are uploaded once per session
// Subsequent tool calls reuse the uploaded document

Workflow:

1. First tool call: Document is uploaded via upload_document tool
2. Document is cached for the session
3. Subsequent tool calls reference the cached document
4. No redundant uploads for multiple operations on same document

Advantages:

• Works with remote MCP servers
• Supports distributed deployments
• Session-based document isolation
• Efficient caching prevents redundant uploads

MCP Server Tools

The Office MCP server provides these document management tools:

Session Management Tools

• upload_document - Upload a document for processing (base64 encoded)
• list_documents - List all documents in a session
• create_document - Create a new document from scratch

Document Operation Tools

All document tools support sessionId parameter for proper document isolation:

• get_paragraphs - Extract paragraphs from a document
• summarize_document - Generate document summary
• update_document - Modify document content
• search_text - Search within documents
• add_paragraph - Add new paragraphs
• update_paragraph - Modify existing paragraphs
• delete_paragraph - Remove paragraphs

Implementation Details

DocumentBridge (App Side)

Located in app/src/vibex/core/document-bridge.ts:

export class DocumentBridge {
  // Intelligently handles document preparation
  async prepareDocument(filename: string): Promise<string> {
    if (this.config.mode === 'shared') {
      // Return filename - MCP can access directly
      return filename;
    } else {
      // Upload if not already uploaded this session
      if (!this.uploadedDocuments.has(sessionKey)) {
        await this.mcpClient.executeTool('upload_document', {
          sessionId: this.config.sessionId,
          documentName: filename,
          content: base64Content
        });
        this.uploadedDocuments.add(sessionKey);
      }
      return filename;
    }
  }
}

MCP Server (C# Side)

The server automatically detects the mode based on environment variables:

DocxToolsConfig.cs

public static string GetDocumentStorePath()
{
    // Check for shared storage configuration
    var vibexPath = Environment.GetEnvironmentVariable("VIBEX_STORAGE_PATH");
    var workspaceId = Environment.GetEnvironmentVariable("VIBEX_PROJECT_ID");

    if (!string.IsNullOrEmpty(vibexPath) && !string.IsNullOrEmpty(workspaceId))
    {
        // Shared storage mode
        return Path.Combine(vibexPath, workspaceId, "documents");
    }

    // Fallback to standalone mode
    return GetDefaultStoragePath();
}

Usage Examples

Example 1: Local Development

# Start with shared storage
pnpm office  # Automatically sets VIBEX_STORAGE_PATH and VIBEX_PROJECT_ID

Example 2: Remote Deployment

// Configure for remote MCP server
const bridge = await createDocumentBridge('my-workspace', {
  mode: 'upload',
  mcpServerUrl: process.env.MCP_SERVER_URL,
  sessionId: generateSessionId()
});

// Prepare document (uploads if needed)
await bridge.prepareDocument('report.docx');

// Use with tools - no redundant uploads
const summary = await mcpClient.executeTool('summarize_document', {
  documentName: 'report.docx',
  sessionId: bridge.config.sessionId
});

Example 3: Cursor/Claude Desktop Integration

The MCP server works as-is with other MCP clients:

// MCP configuration for Cursor/Claude Desktop
{
  "mcpServers": {
    "office": {
      "command": "dotnet",
      "args": ["run", "--workspace", "path/to/OfficeMcp.csproj"],
      "env": {
        // Optional: Set custom storage path
        "OFFICE_MCP_STORAGE": "/custom/path"
      }
    }
  }
}

Benefits of This Architecture

1. Maintains Generic MCP Server: The server doesn’t depend on Vibex-specific code
2. Optimizes for Local Use: Shared storage eliminates unnecessary file transfers
3. Supports Distribution: Upload mode enables remote deployments
4. Session Isolation: Each session has its own document space
5. Efficient Caching: Documents uploaded once per session
6. Backward Compatible: Works with existing MCP clients

Future Enhancements

1. Cloud Storage Integration: Support S3, Azure Blob for truly distributed storage
2. Document Versioning: Track changes across sessions
3. Compression: Compress uploads for large documents
4. Streaming Uploads: Support streaming for very large files
5. Multi-tenant Isolation: Enhanced security for multi-user scenarios