mcp-msaccess-database 0.7.31__py3-none-any.whl

access_mcp_server.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""
+access_mcp_server.py
+====================
+MCP Server for reading and editing Microsoft Access databases (.accdb/.mdb)
+via COM automation (pywin32). Requires Windows + Microsoft Access installed.
+
+Install dependencies:
+    pip install mcp pywin32
+
+Register in Claude Code (one of two methods):
+    # Option A -- global
+    claude mcp add access -- python /path/to/access_mcp_server.py
+
+    # Option B -- this project only (creates .mcp.json in current directory)
+    claude mcp add --scope project access -- python /path/to/access_mcp_server.py
+
+Typical workflow for editing VBA:
+    1. access_list_objects  -> see which modules/forms exist
+    2. access_get_code      -> export the object to text
+    3. (Claude edits the text)
+    4. access_set_code      -> reimport the modified text
+    5. access_close         -> release Access (optional)
+"""
+
+import asyncio
+from mcp_access.server import main
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_access/__init__.py

@@ -0,0 +1 @@
+# mcp_access — MCP Server for Microsoft Access databases

mcp_access/code.py

@@ -0,0 +1,568 @@
+"""
+Object management: list, get, set, delete objects, create form, export structure.
+"""
+
+import os
+import re
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from .core import (
+    AC_TYPE, _Session, _parsed_controls_cache, log,
+    invalidate_all_caches, invalidate_object_caches,
+)
+from .constants import BINARY_SECTIONS, AC_FORM, AC_SAVE_NO
+from .helpers import read_tmp, write_tmp, strip_binary_sections, restore_binary_sections
+
+
+# ---------------------------------------------------------------------------
+# Design-view helpers (used by _inject_vba_after_import)
+# ---------------------------------------------------------------------------
+# These are small private helpers also used by controls module.  Duplicated
+# here to keep the module self-contained; the canonical copy lives in helpers
+# once that module is extended.
+
+_AC_DESIGN   = 1   # acDesign / acViewDesign
+_AC_SAVE_YES = 1   # acSaveYes
+_AC_REPORT   = 3   # acReport
+
+
+def _open_in_design(app: Any, object_type: str, object_name: str) -> None:
+    """Opens a form/report in Design view."""
+    try:
+        if object_type == "form":
+            app.DoCmd.OpenForm(object_name, _AC_DESIGN)
+        else:
+            app.DoCmd.OpenReport(object_name, _AC_DESIGN)
+    except Exception as exc:
+        raise RuntimeError(
+            f"Could not open '{object_name}' in Design view. "
+            f"If it is open in Normal view, close it first.\nError: {exc}"
+        )
+
+
+def _save_and_close(app: Any, object_type: str, object_name: str) -> None:
+    """Saves and closes a form/report open in Design view."""
+    ac_type = AC_FORM if object_type == "form" else _AC_REPORT
+    try:
+        app.DoCmd.Close(ac_type, object_name, _AC_SAVE_YES)
+    except Exception as exc:
+        log.warning("Error closing '%s': %s", object_name, exc)
+
+
+def _get_design_obj(app: Any, object_type: str, object_name: str) -> Any:
+    """Returns the Form or Report object open in Design view."""
+    return app.Forms(object_name) if object_type == "form" else app.Reports(object_name)
+
+
+# ---------------------------------------------------------------------------
+# List objects
+# ---------------------------------------------------------------------------
+
+def ac_list_objects(db_path: str, object_type: str = "all") -> dict:
+    """Returns a dict {type: [names...]} with the database objects."""
+    app = _Session.connect(db_path)
+
+    # CurrentData  -> data objects (tables, queries)
+    # CurrentProject -> code objects (forms, reports, modules, macros)
+    containers = {
+        "table":  app.CurrentData.AllTables,
+        "query":  app.CurrentData.AllQueries,
+        "form":   app.CurrentProject.AllForms,
+        "report": app.CurrentProject.AllReports,
+        "macro":  app.CurrentProject.AllMacros,
+        "module": app.CurrentProject.AllModules,
+    }
+
+    keys = list(containers) if object_type == "all" else [object_type]
+    result: dict[str, list] = {}
+
+    for k in keys:
+        if k not in containers:
+            continue
+        col = containers[k]
+        names = [col.Item(i).Name for i in range(col.Count)]
+        if k == "table":
+            # Filter out system and temp tables
+            names = [n for n in names if not n.startswith("MSys") and not n.startswith("~")]
+        result[k] = names
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Delete object
+# ---------------------------------------------------------------------------
+
+def ac_delete_object(
+    db_path: str, object_type: str, object_name: str, confirm: bool = False,
+) -> dict:
+    """Deletes an Access object (module, form, report, query, macro) via DoCmd.DeleteObject."""
+    if object_type not in AC_TYPE:
+        raise ValueError(
+            f"Invalid object_type '{object_type}'. Valid: {list(AC_TYPE)}"
+        )
+    if not confirm:
+        raise ValueError(
+            "Destructive operation: confirm=true is required to delete an object."
+        )
+    app = _Session.connect(db_path)
+    try:
+        app.DoCmd.DeleteObject(AC_TYPE[object_type], object_name)
+    except Exception as exc:
+        raise RuntimeError(
+            f"Error deleting {object_type} '{object_name}': {exc}"
+        )
+    finally:
+        invalidate_all_caches()
+    return {
+        "action": "deleted",
+        "object_type": object_type,
+        "object_name": object_name,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Get code (export)
+# ---------------------------------------------------------------------------
+
+def ac_get_code(db_path: str, object_type: str, name: str) -> str:
+    """
+    Exports an Access object to text and returns the content.
+    For forms and reports, strips binary sections (PrtMip, PrtDevMode...)
+    that are irrelevant for editing VBA/controls and represent 95% of the size.
+    ac_set_code restores them automatically before importing.
+    """
+    if object_type not in AC_TYPE:
+        raise ValueError(
+            f"Invalid object_type '{object_type}'. Valid: {list(AC_TYPE)}"
+        )
+    app = _Session.connect(db_path)
+
+    fd, tmp = tempfile.mkstemp(suffix=".txt", prefix="access_mcp_")
+    os.close(fd)
+    try:
+        app.SaveAsText(AC_TYPE[object_type], name, tmp)
+        text, _enc = read_tmp(tmp)
+        if object_type in ("form", "report"):
+            text = strip_binary_sections(text)
+        return text
+    finally:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+
+
+# _split_code_behind has moved to helpers.split_code_behind — it was
+# duplicated byte-for-byte in code.py and controls.py. Re-exported here
+# under the old name for backwards compatibility within this module.
+from .helpers import split_code_behind as _split_code_behind  # noqa: E402,F401
+
+
+# ---------------------------------------------------------------------------
+# Class module header injection (for ac_set_code object_type="class_module")
+# ---------------------------------------------------------------------------
+#
+# Access distinguishes class vs standard modules in LoadFromText by the
+# presence of the four Attribute VB_* lines (VB_GlobalNameSpace, VB_Creatable,
+# VB_PredeclaredId, VB_Exposed) at the top of the text -- NOT by a
+# "VERSION 1.0 CLASS" header.  That header is the format used by
+# VBComponent.Export / VBComponents.Import (a different mechanism).  If
+# LoadFromText receives text starting with "VERSION 1.0 CLASS", Access
+# interprets those lines as literal VBA code and creates a *standard*
+# module with garbage at the top.  Tested against Access 2016 on
+# production DB 2026-04-08 — Type=2 only when the 4 attributes are present.
+
+_VB_ATTR_RE = re.compile(r"^\s*Attribute\s+VB_GlobalNameSpace\s*=", re.IGNORECASE)
+# Also detect the legacy (wrong) VERSION header so callers can't accidentally
+# hand us a VBComponent.Export-style file — we'd strip it below.
+_VERSION_CLASS_RE = re.compile(r"^\s*VERSION\s+\d+\.\d+\s+CLASS\s*$", re.IGNORECASE)
+
+
+def _ensure_class_module_header(code: str, name: str) -> str:
+    """Prepend the four Attribute VB_* lines if missing (class module marker).
+
+    `Application.LoadFromText(acModule=5)` decides class vs standard by the
+    presence of these four attribute lines at the top of the file:
+        Attribute VB_GlobalNameSpace = False
+        Attribute VB_Creatable = False
+        Attribute VB_PredeclaredId = False
+        Attribute VB_Exposed = False
+
+    This helper:
+      - strips a leading BOM (if any),
+      - strips any `VERSION 1.0 CLASS` / `BEGIN` / `MultiUse` / `END` /
+        `Attribute VB_Name = "..."` block that the user may have pasted from
+        a VBComponent.Export file (wrong format for LoadFromText),
+      - if `Attribute VB_GlobalNameSpace` is already present in the first
+        handful of non-blank lines, returns code unchanged (round-trip safe),
+      - otherwise prepends the 4 attribute lines,
+      - normalises the body's line endings to CRLF.
+    """
+    if code.startswith("\ufeff"):
+        code = code.lstrip("\ufeff")
+
+    # Strip VBComponent.Export header block if present (wrong format; Access
+    # would interpret these lines as VBA code).  We scan at most 8 lines.
+    lines = code.splitlines()
+    if lines and _VERSION_CLASS_RE.match(lines[0] or ""):
+        # Skip until we see either "END" (end of BEGIN block) or the first
+        # Attribute VB_Name line (which we also strip — LoadFromText takes
+        # the name as a parameter, Attribute VB_Name in the text is ignored
+        # or conflicts).
+        idx = 0
+        saw_end = False
+        for i, ln in enumerate(lines[:8]):
+            stripped = ln.strip()
+            if stripped.upper() == "END":
+                saw_end = True
+                idx = i + 1
+                break
+        if saw_end:
+            lines = lines[idx:]
+            # Also strip a leading Attribute VB_Name = "..." if present
+            while lines and re.match(r'^\s*Attribute\s+VB_Name\s*=', lines[0], re.IGNORECASE):
+                lines = lines[1:]
+        code = "\n".join(lines)
+
+    # Check if the 4 Attribute VB_* lines are already present at top
+    first_lines = [ln for ln in code.splitlines()[:10] if ln.strip()]
+    if any(_VB_ATTR_RE.match(ln) for ln in first_lines):
+        # Normalise endings, return unchanged header-wise
+        body = code.replace("\r\n", "\n").replace("\r", "\n").replace("\n", "\r\n")
+        if body and not body.endswith("\r\n"):
+            body += "\r\n"
+        return body
+
+    header = (
+        "Attribute VB_GlobalNameSpace = False\r\n"
+        "Attribute VB_Creatable = False\r\n"
+        "Attribute VB_PredeclaredId = False\r\n"
+        "Attribute VB_Exposed = False\r\n"
+    )
+
+    # Normalise body to CRLF and ensure trailing newline
+    body = code.replace("\r\n", "\n").replace("\r", "\n").replace("\n", "\r\n")
+    if body and not body.endswith("\r\n"):
+        body += "\r\n"
+
+    return header + body
+
+
+# ---------------------------------------------------------------------------
+# Inject VBA after import
+# ---------------------------------------------------------------------------
+
+def _inject_vba_after_import(app: Any, object_type: str, name: str, vba_code: str) -> None:
+    """
+    Injects VBA code into a form/report after importing it.
+    Activates HasModule by opening in Design view, then uses VBE to insert the code.
+    """
+    if not vba_code.strip():
+        return
+
+    # 1. Open in Design view and activate HasModule
+    _open_in_design(app, object_type, name)
+    try:
+        obj = _get_design_obj(app, object_type, name)
+        obj.HasModule = True
+    finally:
+        _save_and_close(app, object_type, name)
+
+    # 2. Clear VBE cache (module was just created)
+    cache_key = f"{object_type}:{name}"
+    _Session._cm_cache.pop(cache_key, None)
+
+    # 3. Inject code via VBE (lazy import from .vbe)
+    from .vbe import _get_code_module
+    cm = _get_code_module(app, object_type, name)
+    total = cm.CountOfLines
+
+    # Delete auto-generated content by Access (Option Compare Database, etc.)
+    # to avoid duplicates with the VBA we are about to inject
+    if total > 0:
+        cm.DeleteLines(1, total)
+
+    # Normalize line endings to \r\n (VBE requires it)
+    vba_code = vba_code.replace("\r\n", "\n").replace("\r", "\n").replace("\n", "\r\n")
+    if not vba_code.endswith("\r\n"):
+        vba_code += "\r\n"
+
+    # Ensure Option Compare Database and Option Explicit at the top
+    vba_lines = vba_code.split("\r\n")
+    has_compare = any(re.match(r'^\s*Option\s+Compare', l, re.I) for l in vba_lines)
+    has_explicit = any(re.match(r'^\s*Option\s+Explicit', l, re.I) for l in vba_lines)
+    prepend = []
+    if not has_compare:
+        prepend.append("Option Compare Database")
+    if not has_explicit:
+        prepend.append("Option Explicit")
+    if prepend:
+        vba_code = "\r\n".join(prepend) + "\r\n" + vba_code
+
+    cm.InsertLines(1, vba_code)
+
+    # Invalidate caches
+    _Session._cm_cache.pop(cache_key, None)
+
+
+# ---------------------------------------------------------------------------
+# Set code (import)
+# ---------------------------------------------------------------------------
+
+def ac_set_code(db_path: str, object_type: str, name: str, code: str) -> str:
+    """
+    Imports text as an Access object definition (creates or overwrites).
+    For forms and reports, automatically re-injects binary sections
+    (PrtMip, PrtDevMode...) from the current export, so the caller doesn't need
+    to include them in the code they send.
+
+    If the code contains a CodeBehindForm/CodeBehindReport section, it is automatically
+    split: first the form/report is imported without VBA, then the VBA code is injected
+    via VBE (avoiding encoding issues with LoadFromText).
+
+    object_type='class_module' creates a VBA class module: the canonical
+    `VERSION 1.0 CLASS` header is prepended automatically if missing.
+    """
+    valid_types = set(AC_TYPE) | {"class_module"}
+    if object_type not in valid_types:
+        raise ValueError(
+            f"Invalid object_type '{object_type}'. Valid: {sorted(valid_types)}"
+        )
+    # class_module re-uses acModule (5) but with a different text header
+    _ac_type_code = AC_TYPE["module"] if object_type == "class_module" else AC_TYPE[object_type]
+    app = _Session.connect(db_path)
+
+    # Split CodeBehindForm/CodeBehindReport if present
+    vba_code = ""
+    if object_type in ("form", "report"):
+        code, vba_code = _split_code_behind(code)
+        # Remove HasModule from form text — it will be activated when injecting VBA
+        if vba_code:
+            code = re.sub(r"^\s*HasModule\s*=.*$", "", code, flags=re.MULTILINE)
+
+    # If the code doesn't contain binary sections (returned by ac_get_code
+    # with filtering active), restore them from the current form/report.
+    if object_type in ("form", "report") and not any(
+        s in code for s in BINARY_SECTIONS
+    ):
+        log.info("ac_set_code: restoring binary sections for '%s'", name)
+        code = restore_binary_sections(app, object_type, name, code)
+
+    # Ensure class module header is present (no-op if already there)
+    if object_type == "class_module":
+        code = _ensure_class_module_header(code, name)
+
+    # Backup existing object in case import fails
+    backup_tmp = None
+    if object_type in ("form", "report", "module", "class_module"):
+        try:
+            fd_bk, backup_tmp = tempfile.mkstemp(suffix=".txt", prefix="access_mcp_bk_")
+            os.close(fd_bk)
+            app.SaveAsText(_ac_type_code, name, backup_tmp)
+        except Exception:
+            # Doesn't exist yet — no backup needed
+            if backup_tmp:
+                try:
+                    os.unlink(backup_tmp)
+                except OSError:
+                    pass
+            backup_tmp = None
+
+    fd, tmp = tempfile.mkstemp(suffix=".txt", prefix="access_mcp_")
+    os.close(fd)
+    try:
+        # VBA modules (.bas and class modules) expect the system ANSI codepage
+        # (cp1252 on Western Windows, cp1253 on Greek, etc.);
+        # forms/reports/queries/macros expect UTF-16LE with BOM
+        if object_type in ("module", "class_module"):
+            import locale
+            enc = locale.getpreferredencoding(False) or "cp1252"
+        else:
+            enc = "utf-16"
+        write_tmp(tmp, code, encoding=enc)
+        try:
+            app.LoadFromText(_ac_type_code, name, tmp)
+        except Exception as import_exc:
+            # Restaurar backup si existe
+            if backup_tmp and os.path.exists(backup_tmp):
+                log.warning("ac_set_code: import failed, restoring backup for '%s'", name)
+                try:
+                    app.LoadFromText(_ac_type_code, name, backup_tmp)
+                except Exception:
+                    log.error("ac_set_code: could not restore backup for '%s'", name)
+            raise import_exc
+
+        # Invalidate caches for this object (code and controls changed).
+        # class_module also aliases the "module" key because access_get_code
+        # and _get_code_module read via the "module" key for all .bas modules.
+        invalidate_object_caches(object_type, name)
+        if object_type == "class_module":
+            invalidate_object_caches("module", name)
+
+        # Inject VBA if there was CodeBehindForm
+        vba_msg = ""
+        if vba_code:
+            _inject_vba_after_import(app, object_type, name, vba_code)
+            vba_msg = " (with VBA injected via VBE)"
+
+        return f"OK: '{name}' ({object_type}) imported successfully into {db_path}{vba_msg}"
+    finally:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        if backup_tmp:
+            try:
+                os.unlink(backup_tmp)
+            except OSError:
+                pass
+
+
+# ---------------------------------------------------------------------------
+# Create form
+# ---------------------------------------------------------------------------
+
+def ac_create_form(db_path: str, form_name: str, has_header: bool = False) -> dict:
+    """Creates a new form avoiding the 'Save As' MsgBox that blocks COM.
+
+    CreateForm() generates a form with an auto name (Form1, Form2...).
+    DoCmd.Save saves with that name (no dialog).
+    DoCmd.Close with acSaveNo closes (already saved, no dialog).
+    DoCmd.Rename renames to the desired name.
+    """
+    app = _Session.connect(db_path)
+    auto_name = None
+    try:
+        form = app.CreateForm()
+        auto_name = form.Name  # e.g. "Form1"
+
+        if has_header:
+            app.RunCommand(36)  # acCmdFormHdrFtr — toggle header/footer
+
+        # Save with auto-name — no dialog (DoCmd.Save uses current name)
+        app.DoCmd.Save(AC_FORM, auto_name)
+        # Close without prompt (already saved)
+        app.DoCmd.Close(AC_FORM, auto_name, AC_SAVE_NO)
+
+        # Rename to desired name
+        if auto_name != form_name:
+            app.DoCmd.Rename(form_name, AC_FORM, auto_name)
+
+        return {"name": form_name, "created_from": auto_name, "has_header": has_header}
+    except Exception as exc:
+        if auto_name:
+            try:
+                app.DoCmd.Close(AC_FORM, auto_name, AC_SAVE_NO)
+            except Exception:
+                pass
+            try:
+                app.DoCmd.DeleteObject(AC_FORM, auto_name)
+            except Exception:
+                pass
+        raise RuntimeError(f"Error creating form '{form_name}': {exc}")
+    finally:
+        invalidate_all_caches()
+
+
+# ---------------------------------------------------------------------------
+# Export structure
+# ---------------------------------------------------------------------------
+
+def ac_export_structure(db_path: str, output_path: str | None = None) -> str:
+    """
+    Generates a Markdown file with the complete database structure:
+    VBA modules with their function signatures, forms, reports and queries.
+    """
+    from datetime import datetime
+
+    if output_path is None:
+        output_path = str(Path(db_path).parent / "db_structure.md")
+
+    objects = ac_list_objects(db_path, "all")
+    modules  = objects.get("module",  [])
+    forms    = objects.get("form",    [])
+    reports  = objects.get("report",  [])
+    queries  = objects.get("query",   [])
+    macros   = objects.get("macro",   [])
+
+    lines: list[str] = []
+    lines.append(f"# Structure of `{Path(db_path).name}`")
+    lines.append(f"\n**Path**: `{db_path}`  ")
+    lines.append(f"**Generated**: {datetime.now().strftime('%Y-%m-%d %H:%M')}  ")
+    lines.append(
+        f"**Summary**: {len(modules)} modules · {len(forms)} forms · "
+        f"{len(reports)} reports · {len(queries)} queries · {len(macros)} macros\n"
+    )
+
+    # -- VBA Modules with signatures --
+    # Read modules via VBE (no SaveAsText/disk) and warming up the code cache
+    # Lazy imports from .vbe
+    from .vbe import _get_code_module, _cm_all_code
+
+    app = _Session.connect(db_path)
+    lines.append(f"## VBA Modules ({len(modules)})\n")
+    for mod_name in modules:
+        lines.append(f"### `{mod_name}`")
+        try:
+            cm = _get_code_module(app, "module", mod_name)
+            cache_key = f"module:{mod_name}"
+            code = _cm_all_code(cm, cache_key)
+            sigs = []
+            for line in code.splitlines():
+                stripped = line.strip()
+                if re.match(
+                    r"^(Public\s+|Private\s+|Friend\s+)?(Function|Sub)\s+\w+",
+                    stripped,
+                    re.IGNORECASE,
+                ):
+                    sigs.append(f"  - `{stripped}`")
+            if sigs:
+                lines.extend(sigs)
+            else:
+                lines.append("  *(no public functions/subs)*")
+        except Exception as exc:
+            lines.append(f"  *(error reading: {exc})*")
+        lines.append("")
+
+    # -- Forms --
+    lines.append(f"## Forms ({len(forms)})\n")
+    if forms:
+        for name in forms:
+            lines.append(f"- `{name}`")
+    else:
+        lines.append("*(none)*")
+    lines.append("")
+
+    # -- Reports --
+    lines.append(f"## Reports ({len(reports)})\n")
+    if reports:
+        for name in reports:
+            lines.append(f"- `{name}`")
+    else:
+        lines.append("*(none)*")
+    lines.append("")
+
+    # -- Queries --
+    lines.append(f"## Queries ({len(queries)})\n")
+    if queries:
+        for name in queries:
+            lines.append(f"- `{name}`")
+    else:
+        lines.append("*(none)*")
+    lines.append("")
+
+    # -- Macros --
+    if macros:
+        lines.append(f"## Macros ({len(macros)})\n")
+        for name in macros:
+            lines.append(f"- `{name}`")
+        lines.append("")
+
+    content = "\n".join(lines)
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+    return f"[Saved to `{output_path}`]\n\n{content}"