@tanskong/office-assistant 1.0.0

package/README.md

@@ -0,0 +1,57 @@
+# Office Assistant
+
+AI-powered Office automation via MCP protocol.
+
+## Features
+
+- **RunPython**: Execute Python code to control Office applications freely
+- **Smart Workspace**: Desktop folder for safe file processing
+- **Full Office Suite**: Excel, Word, PowerPoint, Outlook, Visio, WPS, and more
+- **License Protection**: Machine-bound license activation
+
+## Installation
+
+```bash
+npx @yourname/office-assistant
+```
+
+## Activation
+
+1. Set environment variable:
+   ```bash
+   set OFFICE_ASSISTANT_LICENSE=OFFICE-ASSISTANT-XXXX-XXXX-XXXX-XXXX
+   ```
+
+2. Run activation:
+   ```bash
+   npx @yourname/office-assistant activate
+   ```
+
+3. Start the server:
+   ```bash
+   npx @yourname/office-assistant
+   ```
+
+## Disclaimer
+
+Please place files in `Desktop/智能办公区/数据` before processing.
+We are not responsible for data loss when operating on original file locations.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `run_python` | Execute Python code (PRIMARY TOOL) |
+| `available_apps` | List installed Office applications |
+| `launch_app` | Launch an Office application |
+| `quit_app` | Quit an Office application |
+| `open_file` | Open an Office file |
+| `save_file` | Save current document |
+| `screenshot` | Capture screenshot |
+| `download` | Download file from URL |
+| `speak` | Text-to-speech |
+| `demonstrate` | Run demonstration |
+
+## License
+
+Commercial license required. See activation instructions above.

package/bin/office-assistant.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * Office Assistant - MCP Server Entry Point
+ * 
+ * This script:
+ * 1. Checks Python environment
+ * 2. Verifies license activation
+ * 3. Launches the Python MCP server
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const PYTHON_SCRIPT = path.join(__dirname, '..', 'src', 'server.py');
+
+function findPython() {
+    // Try 'python' first, then 'python3'
+    const candidates = ['python', 'python3'];
+    for (const cmd of candidates) {
+        try {
+            const result = require('child_process').execSync(`${cmd} --version`, { encoding: 'utf8' });
+            console.log(`[INFO] Found Python: ${result.trim()}`);
+            return cmd;
+        } catch (e) {
+            continue;
+        }
+    }
+    console.error('[ERROR] Python not found. Please install Python 3.10+');
+    process.exit(1);
+}
+
+function main() {
+    const python = findPython();
+    
+    console.log('[INFO] Starting Office Assistant MCP Server...');
+    console.log(`[INFO] Python script: ${PYTHON_SCRIPT}`);
+    
+    const args = process.argv.slice(2);
+    const server = spawn(python, [PYTHON_SCRIPT, ...args], {
+        stdio: ['inherit', 'inherit', 'inherit']
+    });
+    
+    server.on('close', (code) => {
+        process.exit(code);
+    });
+    
+    server.on('error', (err) => {
+        console.error('[ERROR] Failed to start server:', err.message);
+        process.exit(1);
+    });
+}
+
+main();

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tanskong/office-assistant",
+  "version": "1.0.0",
+  "description": "Office Assistant - AI-powered Office automation via MCP protocol with license protection",
+  "main": "bin/office-assistant.js",
+  "bin": {
+    "office-assistant": "bin/office-assistant.js"
+  },
+  "scripts": {
+    "start": "node bin/office-assistant.js",
+    "activate": "node bin/office-assistant.js activate",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "mcp",
+    "office",
+    "excel",
+    "word",
+    "powerpoint",
+    "automation",
+    "ai",
+    "microsoft-office",
+    "wps"
+  ],
+  "author": "tanskong",
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "win32"
+  ],
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "requirements.txt"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourname/office-assistant.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourname/office-assistant/issues"
+  },
+  "homepage": "https://github.com/yourname/office-assistant#readme"
+}

package/requirements.txt

@@ -0,0 +1,3 @@
+fastmcp>=2.3.3
+pywin32>=310
+Pillow>=10.0.0

package/src/.dev_mode

@@ -0,0 +1,2 @@
+# Development mode marker - remove before release
+# This file bypasses license verification for development

package/src/license_manager.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""
+Office Assistant License Activation System
+==========================================
+1. User activates with license key
+2. System captures MAC address and machine fingerprint
+3. Saves activation record locally
+4. On every startup, verifies MAC address matches
+"""
+
+import os
+import sys
+import json
+import hashlib
+import uuid
+import socket
+import subprocess
+from datetime import datetime
+
+APP_DATA_DIR = os.path.join(os.environ.get("APPDATA", os.path.dirname(__file__)), "office-assistant")
+ACTIVATION_FILE = os.path.join(APP_DATA_DIR, "activation.dat")
+
+
+def get_mac_address():
+    mac = ':'.join(['{:02x}'.format((uuid.getnode() >> i) & 0xff) for i in range(0, 48, 8)][::-1])
+    return mac.upper().replace(':', '')
+
+
+def get_machine_fingerprint():
+    mac = get_mac_address()
+    hostname = socket.gethostname()
+    try:
+        result = subprocess.run(['wmic', 'cpu', 'get', 'ProcessorId'], capture_output=True, text=True)
+        cpu_id = result.stdout.strip().split('\n')[-1].strip()
+    except:
+        cpu_id = 'CPU-UNKNOWN'
+    combined = f"{mac}|{hostname}|{cpu_id}"
+    return hashlib.sha256(combined.encode()).hexdigest()[:32].upper()
+
+
+def get_license_key():
+    return os.environ.get("OFFICE_ASSISTANT_LICENSE", "")
+
+
+def validate_key_format(key):
+    if not key:
+        return False, "No license key provided"
+    key = key.strip()
+    if not key.startswith("OFFICE-ASSISTANT-"):
+        return False, "Invalid key format. Key must start with OFFICE-ASSISTANT-"
+    return True, "OK"
+
+
+def activate(key):
+    print("\n" + "=" * 50)
+    print("  Office Assistant Activation")
+    print("=" * 50)
+
+    if not key:
+        print("\n[ERROR] No license key provided!")
+        print("\nPlease set environment variable OFFICE_ASSISTANT_LICENSE")
+        print("  Windows: set OFFICE_ASSISTANT_LICENSE=your-key")
+        return False
+
+    valid, msg = validate_key_format(key)
+    if not valid:
+        print(f"\n[ERROR] Invalid license key: {key}")
+        print(f"   Error: {msg}")
+        return False
+
+    if os.path.exists(ACTIVATION_FILE):
+        print("\n[WARN] Already activated!")
+        print(f"   Activation file: {ACTIVATION_FILE}")
+        print("\n   To re-activate, delete activation.dat first.")
+        return False
+
+    os.makedirs(APP_DATA_DIR, exist_ok=True)
+
+    mac = get_mac_address()
+    fingerprint = get_machine_fingerprint()
+
+    activation_data = {
+        "license_key": key.strip(),
+        "mac_address": mac,
+        "fingerprint": fingerprint,
+        "activated_at": datetime.now().isoformat(),
+        "hostname": socket.gethostname()
+    }
+
+    with open(ACTIVATION_FILE, 'w') as f:
+        json.dump(activation_data, f, indent=2)
+
+    print("\n[OK] Activation Successful!")
+    print(f"\n   License Key: {key}")
+    print(f"   MAC Address: {mac}")
+    print(f"   Fingerprint: {fingerprint}")
+    print(f"   Activated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print(f"\n   Activation file: {ACTIVATION_FILE}")
+    print(f"\n   This computer is now bound to this license.")
+    print("=" * 50)
+    return True
+
+
+def verify_license():
+    """Verify license on server startup"""
+    dev_marker = os.path.join(os.path.dirname(__file__), ".dev_mode")
+    if os.path.exists(dev_marker):
+        return True
+
+    if not os.path.exists(ACTIVATION_FILE):
+        print("[ERROR] Office Assistant is not activated. Please run activation first.")
+        sys.exit(1)
+
+    try:
+        with open(ACTIVATION_FILE, 'r') as f:
+            data = json.load(f)
+
+        current_mac = get_mac_address()
+        current_fingerprint = get_machine_fingerprint()
+        stored_mac = data.get("mac_address", "")
+        stored_fingerprint = data.get("fingerprint", "")
+        stored_key = data.get("license_key", "").strip()
+        current_key = os.environ.get("OFFICE_ASSISTANT_LICENSE", "").strip()
+
+        if current_key != stored_key:
+            print("[ERROR] License key mismatch.")
+            sys.exit(1)
+
+        if current_mac != stored_mac or current_fingerprint != stored_fingerprint:
+            print("[ERROR] License is bound to another device.")
+            sys.exit(1)
+
+    except Exception as e:
+        print(f"[ERROR] License verification failed: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    key = get_license_key()
+    success = activate(key)
+    sys.exit(0 if success else 1)

package/src/officer.py

@@ -0,0 +1,391 @@
+import winreg
+import pywintypes
+import os
+import sys
+import win32com.client
+from pathlib import Path
+
+
+class TheOfficer:
+    def __init__(self):
+        self._excel = None
+        self._word = None
+        self._outlook = None
+        self._visio = None
+        self._access = None
+        self._project = None
+        self._publisher = None
+        self._onenote = None
+        self._powerpoint = None
+        self._ket = None
+        self._kwpp = None
+        self._kwps = None
+
+        self._default_folder = "D:\\@OfficeMCP"
+        self.Version = "1.0.5"
+        self.Speaker = None
+        self.ComObjects = {}
+        self._printable = False
+        self.Data = OfficerData()
+
+        self.MicrosoftApplications = [
+            'Word', 'Excel', 'PowerPoint',
+            'Visio', 'Access', 'MSProject',
+            'Outlook', 'Publisher', "OneNote", "Kwps", "Ket", "Kwpp"
+        ]
+
+    @property
+    def RootFolder(self) -> str:
+        if not os.path.exists(self._default_folder):
+            os.makedirs(self._default_folder)
+        return self._default_folder
+
+    def GetComObject(self, com_name: str, active: bool = True):
+        comobject = self.ComObjects.get(com_name)
+        if comobject is None:
+            try:
+                comobject = win32com.client.GetActiveObject(com_name)
+            except Exception:
+                comobject = win32com.client.Dispatch(com_name)
+            self.ComObjects[com_name] = comobject
+        return comobject
+
+    def Speak(self, text: str = "Hello!, I'm Office Assistant.", volume: int = 80, rate: int = 2) -> bool:
+        try:
+            if self.Speaker is None:
+                self.Speaker = self.GetComObject("SAPI.SPVOICE")
+            self.Speaker.Volume = volume
+            self.Speaker.Rate = rate
+            self.Speaker.Speak(text)
+            return True
+        except Exception as e:
+            print(e)
+            return False
+
+    def DownloadImage(self, url: str, save_path: str = None) -> str:
+        import datetime
+        if save_path is None:
+            now = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+            save_path = f"downloaded_{now}.png"
+        return self.DownloadURL(url, save_path)
+
+    def DownloadURL(self, url: str, save_path: str = None) -> str:
+        import urllib.request
+        import datetime
+        if save_path is None:
+            now = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+            save_path = f"downloaded_{now}.png"
+        file_path = self.FilePath(save_path)
+        try:
+            with urllib.request.urlopen(url) as response, open(file_path, 'wb') as out_file:
+                out_file.write(response.read())
+            return file_path
+        except Exception as e:
+            print(f'Download failed: {e}')
+            return ""
+
+    def Visible(self, app_name: str, visible=None) -> bool:
+        try:
+            app = self.Application(app_name)
+            if app is None:
+                return False
+            if visible is not None:
+                app.Visible = visible
+            return app.Visible
+        except Exception as e:
+            print(e)
+            return False
+
+    def Quit(self, app_name: str, force: bool = False) -> bool:
+        app_name_attr = "_" + app_name.lower()
+        if hasattr(self, app_name_attr):
+            app = getattr(self, app_name_attr)
+            try:
+                return self.QuitApplication(app, force)
+            except Exception as e:
+                print(e)
+        return False
+
+    def QuitApplication(self, app, force: bool = False) -> bool:
+        if not force:
+            try:
+                app.Quit()
+                return True
+            except Exception as e:
+                print(e)
+                return False
+        import win32process
+        import win32api
+        import win32con
+        hwnd = app.Hwnd
+        t, p = win32process.GetWindowThreadProcessId(hwnd)
+        try:
+            handle = win32api.OpenProcess(win32con.PROCESS_TERMINATE, 0, p)
+            if handle:
+                win32api.TerminateProcess(handle, 0)
+                win32api.CloseHandle(handle)
+                return True
+        except:
+            pass
+        return False
+
+    def Application(self, app_name: str, asNewInstance: bool = False):
+        app_name_attr = "_" + app_name.lower()
+        if hasattr(self, app_name_attr):
+            app = getattr(self, app_name_attr)
+            try:
+                name = app.Name
+                return app
+            except Exception:
+                pass
+        if app_name not in self.MicrosoftApplications:
+            return None
+        if not self.IsAppAvailable(app_name):
+            return None
+        app_full_name = app_name + ".Application"
+        if asNewInstance:
+            app = win32com.client.Dispatch(app_full_name)
+            self.__dict__[app_name_attr] = app
+            return app
+        else:
+            try:
+                app = win32com.client.GetActiveObject(app_full_name)
+            except pywintypes.com_error:
+                app = win32com.client.Dispatch(app_full_name)
+            self.__dict__[app_name_attr] = app
+            return app
+
+    def RunningApps(self) -> list:
+        apps = []
+        for prog_id in self.MicrosoftApplications:
+            try:
+                app = win32com.client.GetActiveObject(prog_id + ".Application")
+                if app is not None:
+                    apps.append(prog_id)
+            except (FileNotFoundError, pywintypes.com_error):
+                continue
+            except Exception as e:
+                print(f"[DEBUG] Error verifying {prog_id}: {str(e)}")
+        return apps
+
+    def AvailableApps(self) -> list:
+        apps = []
+        for prog_id in self.MicrosoftApplications:
+            try:
+                with winreg.OpenKey(winreg.HKEY_CLASSES_ROOT, prog_id + ".Application"):
+                    pass
+                apps.append(prog_id)
+            except (FileNotFoundError, pywintypes.com_error):
+                continue
+            except Exception as e:
+                print(f"[DEBUG] Error verifying {prog_id}: {str(e)}")
+        return apps
+
+    def IsAppAvailable(self, app_name: str) -> bool:
+        try:
+            if not app_name.endswith(".Application"):
+                app_name = app_name + ".Application"
+            with winreg.OpenKey(winreg.HKEY_CLASSES_ROOT, app_name):
+                pass
+            return True
+        except Exception:
+            return False
+
+    def Demonstrate(self) -> str:
+        if not self.DemonstrateExcel():
+            return "There's no Excel installed or something wrong"
+        if not self.DemonstratePowerPoint():
+            return "There's no PowerPoint installed or something wrong"
+        return "Demo succeeded"
+
+    def DemonstrateExcel(self) -> bool:
+        excel = self.Excel
+        if excel is None:
+            return False
+        book = excel.Workbooks.Add()
+        sheet = excel.ActiveSheet
+        excel.Visible = True
+        sheet.Cells(1, 1).Value = "Hello, World From Office Assistant!"
+        sheet.Cells(1, 1).Font.Size = 20
+        sheet.Cells(1, 1).Font.Bold = True
+        sheet.Cells(2, 1).Value = "This is a demonstration of the Office Assistant server."
+        sheet.Cells(3, 1).Value = "You can use run_python tool to control all Microsoft Office Applications."
+        return True
+
+    def DemonstratePowerPoint(self) -> bool:
+        ppt = self.Application("PowerPoint")
+        if ppt is None:
+            return False
+        ppt.Visible = True
+        presentation = ppt.Presentations.Add()
+        slide = presentation.Slides.Add(1, 12)
+        shape = slide.Shapes.AddTextbox(1, 100, 20, 800, 100)
+        shape.TextFrame.TextRange.Text = "Hello, World From Office Assistant!"
+        shape.TextFrame.TextRange.Font.Bold = True
+        return True
+
+    def FilePath(self, file_name: str = None, subfolder: str = None) -> str:
+        if subfolder is None:
+            file_path = os.path.join(self.RootFolder, file_name)
+        else:
+            file_path = os.path.join(self.RootFolder, subfolder, file_name)
+        return file_path
+
+    def ScreenShot(self, save_path: str = None) -> str:
+        import win32gui
+        import win32ui
+        import win32con
+        import win32api
+        from PIL import Image
+        import datetime
+        hdesktop = win32gui.GetDesktopWindow()
+        width = win32api.GetSystemMetrics(win32con.SM_CXVIRTUALSCREEN)
+        height = win32api.GetSystemMetrics(win32con.SM_CYVIRTUALSCREEN)
+        left = win32api.GetSystemMetrics(win32con.SM_XVIRTUALSCREEN)
+        top = win32api.GetSystemMetrics(win32con.SM_YVIRTUALSCREEN)
+        desktop_dc = win32gui.GetWindowDC(hdesktop)
+        img_dc = win32ui.CreateDCFromHandle(desktop_dc)
+        mem_dc = img_dc.CreateCompatibleDC()
+        screenshot = win32ui.CreateBitmap()
+        screenshot.CreateCompatibleBitmap(img_dc, width, height)
+        mem_dc.SelectObject(screenshot)
+        mem_dc.BitBlt((0, 0), (width, height), img_dc, (left, top), win32con.SRCCOPY)
+        bmpinfo = screenshot.GetInfo()
+        bmpstr = screenshot.GetBitmapBits(True)
+        img = Image.frombuffer(
+            'RGB',
+            (bmpinfo['bmWidth'], bmpinfo['bmHeight']),
+            bmpstr, 'raw', 'BGRX', 0, 1)
+        if save_path is None:
+            now = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+            save_path = self.FilePath(f"screenshot_{now}.png")
+        else:
+            save_path = self.FilePath(save_path)
+        img.save(save_path)
+        mem_dc.DeleteDC()
+        win32gui.DeleteObject(screenshot.GetHandle())
+        img_dc.DeleteDC()
+        win32gui.ReleaseDC(hdesktop, desktop_dc)
+        return save_path
+
+    @property
+    def Kwps(self):
+        try:
+            name = self._kwps.Name
+            return self._kwps
+        except Exception:
+            self._kwps = self.Application("Kwps", False)
+        return self._kwps
+
+    @property
+    def Ket(self):
+        try:
+            name = self._ket.Name
+            return self._ket
+        except Exception:
+            self._ket = self.Application("Ket", False)
+        return self._ket
+
+    @property
+    def Kwpp(self):
+        try:
+            name = self._kwpp.Name
+            return self._kwpp
+        except Exception:
+            self._kwpp = self.Application("Kwpp", False)
+        return self._kwpp
+
+    @property
+    def Excel(self):
+        try:
+            name = self._excel.Name
+            return self._excel
+        except Exception:
+            self._excel = self.Application("Excel", False)
+        return self._excel
+
+    @property
+    def Word(self):
+        try:
+            name = self._word.Name
+            return self._word
+        except Exception:
+            self._word = self.Application("Word", False)
+        return self._word
+
+    @property
+    def PowerPoint(self):
+        try:
+            name = self._powerpoint.Name
+            return self._powerpoint
+        except Exception:
+            self._powerpoint = self.Application("PowerPoint", False)
+        return self._powerpoint
+
+    @property
+    def Visio(self):
+        try:
+            name = self._visio.Name
+            return self._visio
+        except Exception:
+            self._visio = self.Application("Visio", False)
+        return self._visio
+
+    @property
+    def Access(self):
+        try:
+            name = self._access.Name
+            return self._access
+        except Exception:
+            self._access = self.Application("Access", False)
+        return self._access
+
+    @property
+    def Project(self):
+        try:
+            name = self._project.Name
+            return self._project
+        except Exception:
+            self._project = self.Application("MSProject", False)
+        return self._project
+
+    @property
+    def Outlook(self):
+        try:
+            name = self._outlook.Name
+            return self._outlook
+        except Exception:
+            self._outlook = self.Application("Outlook", False)
+        return self._outlook
+
+    @property
+    def Publisher(self):
+        try:
+            name = self._publisher.Name
+            return self._publisher
+        except Exception:
+            self._publisher = self.Application("Publisher", False)
+        return self._publisher
+
+    @property
+    def OneNote(self):
+        try:
+            name = self._onenote.Name
+            return self._onenote
+        except Exception:
+            self._onenote = self.Application("OneNote", False)
+        return self._onenote
+
+
+class OfficerData:
+    def init(self):
+        current_attrs = set(vars(self).keys())
+        for attr in current_attrs - self._initial_attrs:
+            delattr(self, attr)
+        self.data = {}
+        self.output = ""
+        self.helloworld = "Hello World"
+
+    def __init__(self):
+        self._initial_attrs = set(vars(self).keys())
+        self.init()

package/src/server.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""
+Office Assistant MCP Server
+===========================
+Minimalist design: RunPython as the primary tool.
+Smart Office Workspace on Desktop for data safety.
+
+Disclaimer: Please place files in "Desktop/智能办公区/数据" before processing.
+We are not responsible for data loss when operating on original file locations.
+"""
+
+import sys
+import os
+
+from license_manager import verify_license
+verify_license()
+
+from fastmcp import FastMCP
+from officer import TheOfficer
+from utils import get_workspace, get_data_dir, get_export_dir, get_download_dir
+
+mcp = FastMCP("Office Assistant")
+Officer = TheOfficer()
+
+APP_MAP = {
+    'xlsx': 'Excel', 'xls': 'Excel', 'csv': 'Excel',
+    'docx': 'Word', 'doc': 'Word',
+    'pptx': 'PowerPoint', 'ppt': 'PowerPoint',
+}
+
+
+def _get_active_doc(app, app_name):
+    try:
+        if app_name.lower() in ['excel', 'ket']:
+            return app.ActiveWorkbook
+        elif app_name.lower() in ['word', 'kwps']:
+            return app.ActiveDocument
+        elif app_name.lower() in ['powerpoint', 'kwpp']:
+            return app.ActivePresentation
+    except:
+        return None
+
+
+def _build_globals(app, doc, app_name):
+    base = {
+        'app': app,
+        'doc': doc,
+        'Officer': Officer,
+        '__builtins__': __builtins__,
+    }
+    if app_name.lower() in ['excel', 'ket']:
+        base['sheet'] = doc.ActiveSheet if doc else None
+    elif app_name.lower() in ['word', 'kwps']:
+        base['selection'] = app.Selection
+    elif app_name.lower() in ['powerpoint', 'kwpp']:
+        base['slide'] = doc.Slides(doc.Slides.Count) if doc else None
+    return base
+
+
+# ========== Application Control Tools ==========
+
+@mcp.tool()
+def available_apps() -> list:
+    """List installed Microsoft Office applications."""
+    return Officer.AvailableApps()
+
+
+@mcp.tool()
+def launch_app(app_name: str = "Excel", visible: bool = True) -> bool:
+    """Launch a Microsoft Office application."""
+    try:
+        app = Officer.Application(app_name)
+        app.Visible = visible
+        return True
+    except Exception as e:
+        print(f"Launch failed: {e}")
+        return False
+
+
+@mcp.tool()
+def quit_app(app_name: str = "Excel", force: bool = False) -> bool:
+    """Quit a Microsoft Office application."""
+    return Officer.Quit(app_name, force)
+
+
+# ========== File Operation Tools ==========
+
+@mcp.tool()
+def open_file(file_path: str) -> dict:
+    """
+    Open an Office file.
+
+    Supported formats:
+    - Excel: .xlsx, .xls, .csv
+    - Word: .docx, .doc
+    - PowerPoint: .pptx, .ppt
+
+    Tip: Place files in "Desktop/智能办公区/数据" for safe processing.
+    """
+    ext = file_path.split('.')[-1].lower()
+    app_name = APP_MAP.get(ext, 'Excel')
+    app = Officer.Application(app_name)
+
+    if app_name == 'Excel':
+        doc = app.Workbooks.Open(file_path)
+    elif app_name == 'Word':
+        doc = app.Documents.Open(file_path)
+    elif app_name == 'PowerPoint':
+        doc = app.Presentations.Open(file_path)
+
+    app.Visible = True
+    return {"success": True, "app": app_name, "file": file_path}
+
+
+@mcp.tool()
+def save_file(file_path: str = None) -> dict:
+    """Save the current active document."""
+    for app_name in ['Excel', 'Word', 'PowerPoint']:
+        try:
+            app = Officer.Application(app_name)
+            if app_name == 'Excel':
+                doc = app.ActiveWorkbook
+            elif app_name == 'Word':
+                doc = app.ActiveDocument
+            else:
+                doc = app.ActivePresentation
+
+            if doc:
+                if file_path:
+                    doc.SaveAs(file_path)
+                else:
+                    doc.Save()
+                return {"success": True, "file": doc.FullName}
+        except:
+            continue
+    return {"success": False, "error": "No active document found"}
+
+
+# ========== Core Tool: RunPython ==========
+
+@mcp.tool()
+def run_python(code: str, app_name: str = "Excel") -> dict:
+    """
+    Execute Python code to control Office applications (PRIMARY TOOL).
+
+    Available global variables:
+    - app: The Office application object
+    - doc: The current active document
+    - sheet: Active worksheet (Excel)
+    - selection: Current selection (Word)
+    - slide: Active slide (PowerPoint)
+    - Officer: TheOfficer instance for accessing other apps
+
+    Excel example:
+        sheet.Cells(1, 1).Value = "Hello"
+        doc.Save()
+
+    Word example:
+        doc.Content.Text = "Hello World"
+        doc.Save()
+
+    PowerPoint example:
+        slide.Shapes.AddTextbox(1, 100, 100, 400, 50).TextFrame.TextRange.Text = "Title"
+    """
+    app = Officer.Application(app_name)
+    doc = _get_active_doc(app, app_name)
+    globals_dict = _build_globals(app, doc, app_name)
+
+    try:
+        exec(code, globals_dict)
+        return {"success": True}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+# ========== System Tools ==========
+
+@mcp.tool()
+def screenshot(save_name: str = None) -> str:
+    """Capture a screenshot and save to the export folder."""
+    path = Officer.ScreenShot(save_name)
+    return path
+
+
+@mcp.tool()
+def download(url: str, save_name: str = None) -> str:
+    """Download a file from URL to the download folder."""
+    return Officer.DownloadURL(url, save_name)
+
+
+@mcp.tool()
+def speak(text: str = "Hello", volume: int = 80, rate: int = 0) -> bool:
+    """Text-to-speech. Volume: 0-100, Rate: -10 to 10."""
+    return Officer.Speak(text, volume, rate)
+
+
+@mcp.tool()
+def demonstrate() -> dict:
+    """Run a demonstration of Office automation capabilities."""
+    try:
+        result = Officer.Demonstrate()
+        return {"success": True, "output": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+@mcp.resource("resource://instructions")
+def get_instructions() -> str:
+    """Get usage instructions and disclaimer."""
+    workspace = get_workspace()
+    return f"""
+    ╔══════════════════════════════════════════════════════════════╗
+    ║              Office Assistant - 使用指南                      ║
+    ╚══════════════════════════════════════════════════════════════╝
+
+    【免责声明】
+    请将需要处理的文件复制到「桌面/智能办公区/数据」文件夹后再操作。
+    直接在原文件位置操作导致的数据丢失，本软件概不负责。
+
+    工作目录: {workspace}
+      - 数据/: 放置源文件
+      - 导出/: 截图、PDF等导出文件
+      - 下载/: 下载的文件
+
+    【主力工具: run_python】
+    执行 Python 代码控制 Office 应用。
+
+    可用变量:
+      - app: Office 应用对象
+      - doc: 当前文档
+      - sheet: 当前工作表 (Excel)
+      - selection: 当前选区 (Word)
+      - slide: 当前幻灯片 (PowerPoint)
+      - Officer: 办公助手 (Officer.Excel, Officer.Word 等)
+
+    【Excel 示例】
+        sheet.Cells(1, 1).Value = "Hello"
+        sheet.Cells(1, 1).Font.Bold = True
+        doc.Save()
+
+    【Word 示例】
+        doc.Content.Text = "Hello World"
+        doc.Save()
+
+    【PowerPoint 示例】
+        slide.Shapes.AddTextbox(1, 100, 100, 400, 50).TextFrame.TextRange.Text = "Title"
+    """
+
+
+# ========== Entry Point ==========
+
+def run():
+    args = sys.argv[1:]
+    transport = args[0].lower() if args else "stdio"
+
+    if transport == "stdio":
+        print("Office Assistant started (stdio mode)")
+        mcp.run("stdio")
+    else:
+        host = "127.0.0.1"
+        port = 8888
+        print(f"Office Assistant started (SSE mode: http://{host}:{port}/sse)")
+        mcp.run(transport="sse", host=host, port=port)
+
+
+if __name__ == "__main__":
+    run()

package/src/utils.py

@@ -0,0 +1,24 @@
+from pathlib import Path
+
+
+def get_workspace():
+    """Get or create the smart office workspace on Desktop"""
+    desktop = Path.home() / "Desktop"
+    workspace = desktop / "智能办公区"
+    workspace.mkdir(exist_ok=True)
+    (workspace / "数据").mkdir(exist_ok=True)
+    (workspace / "导出").mkdir(exist_ok=True)
+    (workspace / "下载").mkdir(exist_ok=True)
+    return workspace
+
+
+def get_data_dir():
+    return get_workspace() / "数据"
+
+
+def get_export_dir():
+    return get_workspace() / "导出"
+
+
+def get_download_dir():
+    return get_workspace() / "下载"