Focused harness for safe M-Files vault inspection and administration through M-Files Admin, the COM API, and VAF configuration domains.

Start with AGENTS.md. It routes each task to the correct skill, reference, and deterministic script.

1. Copy scripts/vaults.example.json to scripts/vaults.json.
2. Add local vault GUIDs, passwords, and M-Files Admin connection names.
3. Keep scripts/vaults.json local; Git ignores it.
4. Run scripts/Test-VaultOperationsHarness.ps1.

Reusable PowerShell code lives in the MFilesVaultOperations module. Its Public/ and Private/ folders contain one function per file; stable command wrappers remain at the skill's scripts/ root.

UIX and VAF application development are intentionally excluded from this repository.

The repository includes a local STDIO MCP server that adapts the supported PowerShell operations to focused, schema-validated tools. It runs directly from source on Windows and does not expose credentials, connection strings, or complete vault configuration payloads.

Prerequisites:

• Node.js 20 or newer;
• Windows PowerShell 5.1;
• M-Files Client/Admin and the COM API on the same Windows host;
• scripts/vaults.json with the exact local vault aliases;
• trusted project-scoped Codex configuration.

Install and verify:

npm install
npm run test:harness
npm test

Run the server manually:

npm start

Codex reads the project-scoped configuration from .codex/config.toml. It starts node mcp/server.mjs in this repository, prompts for non-read-only tools, and currently allows guarded writes to the exact aliases Purchasing and SMC-DEV. Restart Codex after changing this configuration.

The Node bridge uses a persistent Windows PowerShell worker by default. The worker loads the M-Files module and each dispatcher handler once, then serves single-flight framed JSON requests over a per-process named pipe. A timeout, protocol error, or worker crash terminates the worker and the next request starts a clean one; write operations are never retried automatically.

The worker does not cache COM sessions, credentials, authorization tokens, mutable configuration, or vault-local IDs between requests. For troubleshooting or compatibility testing, set MFILES_BRIDGE_PERSISTENT=false to restore the one-process-per-call bridge. MFILES_BRIDGE_TIMEOUT_MS and MFILES_MAX_OUTPUT_BYTES continue to apply to both modes.

The default profile is all for backward compatibility. Set MFILES_TOOL_PROFILE to one profile, or a comma-separated union, before starting the server:

• core-read: fast health/diagnostics, connectivity, metadata alias, and lookup resolution;
• metadata: object, object-type, property-definition, value-list, and class read/validate tools;
• workflow: workflow and common-view read/validate tools;
• configuration: configuration domain, Metadata Card, Property Calculator, and Prime Kit Excel read/validate tools;
• compliance: Compliance Kit read/validate tools;
• writes: consequential validate/write/apply surface;
• all: the complete public surface.

Domain profiles intentionally omit consequential writes. Profile selection does not change the PowerShell dispatcher allowlist or any validation token, vault confirmation, writable allowlist, or SMC-PROD guard. Unknown profiles fail server startup. Run npm run docs:check to verify this table matches the catalog.

Workflow CRUD supports aliased graph creation, explicit or live Named ACL-derived state permissions, state pre/postcondition VBScript fingerprints, transition trigger/evaluation fields, focused statePermissionUpdates and transitionUpdates, and identity update/delete. Raw scripts and complete ACL payloads are never returned.

The project MCP configuration uses cwd = "..". Codex resolves this relative path from the project .codex directory, keeping the tracked configuration portable across checkouts while still starting the server at the repository root. Machine-specific one-off overrides can use Codex's -c configuration override; do not commit credentials or expand MFILES_WRITABLE_VAULTS as a portability workaround.

A class, object-type, property-definition, value-list, or supported workflow migration must use the one-time token produced by the matching preflight. A configuration save must use the one-time token produced by validating the exact same JSON text. Tokens expire after ten minutes and are consumed before the write begins so a failed or timed-out write cannot be blindly replayed.

Every write also requires:

• allowWrite: true;
• confirmedWritableAlias exactly matching the target;
• the target alias in the server-side MFILES_WRITABLE_VAULTS allowlist;
• Codex approval according to .codex/config.toml;
• a target other than the permanently read-only SMC-PROD.

Rollback is disabled by default. Class migration rollback requires both rollbackOnFailure: true and allowRollback: true; these flags do not replace the user's explicit authorization of rollback scope.

The configuration tools intentionally do not return a complete domain payload. The caller must supply the candidate JSON to validation and then supply the same exact text to the guarded save operation.

Managed Property changes use semantic aliases and clone one existing template rule. The validation token binds the candidate plus the current Managed Properties configuration SHA-256, preventing an intervening configuration change from being overwritten. Staging and Apply are deliberately separate: mfiles_managed_property_rule_write leaves changes pending, while mfiles_compliance_apply requires a second token and allowModuleRestart: true.

For other Compliance Kit modules, call mfiles_compliance_module_list first, then mfiles_compliance_module_analyze. For Hierarchy Manager, call mfiles_compliance_hierarchy_manager_analyze and read .agents/skills/mfiles-admin-vault-operations/references/hierarchy-manager-patterns.md. For Object Creator, call mfiles_compliance_object_creator_analyze and read .agents/skills/mfiles-admin-vault-operations/references/object-creator-patterns.md. Continue investigation only for the active configured modules reported in researchScope; disabled modules with default/comment-only configuration are not treated as available features. The live SMC-DEV pattern snapshot is documented in .agents/skills/mfiles-admin-vault-operations/references/compliance-kit-patterns.md.

Property Calculator, Prime Kit Excel, and Metadata Card writes use scoped candidates instead of complete configuration payloads:

{
  "propertyCalculator": {
    "action": "update",
    "groupName": "Common Rules",
    "ruleName": "PO lookup",
    "rule": { "Name": "PO lookup", "SetValueTo": "PD.A21PurchaseOrder" }
  },
  "primeKitExcel": {
    "action": "update",
    "ruleName": "Purchase Order Line Items",
    "actionType": "Item Lines",
    "rule": { "Name": "Purchase Order Line Items", "ActionType": "Item Lines" }
  },
  "metadataCardProperty": {
    "action": "update",
    "resource": "property",
    "ruleGuid": "rule-guid",
    "name": "PD.PurchaseOrderLineItems",
    "value": {
      "Property": "PD.PurchaseOrderLineItems",
      "Group": "Line Items Object"
    }
  }
}

Each validation builds the complete candidate internally and runs the domain's native validator. The token binds the scoped candidate and current configuration SHA-256. The write reloads the domain, rejects drift, validates again, saves once, and requires an exact SHA-256 read-back.

Property Calculator migration is a separate source-to-target flow. Analyze the source, compare vaults when needed, then preflight one exact group or rule. The preflight resolves semantic dependencies in both vaults and returns only sanitized dependency status, blockers, warnings, selected rule names, and the target configuration SHA-256. The migration token is bound to that hash and the exact selectors; the guarded writer appends only missing rules and verifies selected-rule hashes after read-back.

Each CRUD write is a two-call sequence:

1. Call the resource-specific *_validate tool with vaultAlias, action, and the complete candidate.
2. Review blockers, warnings, and the exact target. Then call the matching *_write tool with the unchanged candidate, one-time validationToken, exact confirmedWritableAlias, and allowWrite: true.

The token is bound to the resource, action, vault alias, and candidate SHA-256. Write operations re-run preflight inside the connected session. Deletes are destructive metadata operations except object deletion, which is a recoverable soft-delete. The adapter never exposes DestroyObject.

Candidate shapes:

{
  "object": {
    "create": {
      "objectTypeAlias": "OT.CodexTest",
      "classAlias": "CL.CodexTest",
      "properties": [
        { "propertyAlias": "PD.Title", "value": "Example" },
        { "propertyAlias": "PD.Status", "lookupId": 12 }
      ]
    },
    "update": {
      "objectTypeAlias": "OT.CodexTest",
      "objectId": 42,
      "expectedVersion": 3,
      "properties": [
        { "propertyAlias": "PD.Enabled", "value": true }
      ]
    },
    "delete": {
      "objectTypeAlias": "OT.CodexTest",
      "objectId": 42,
      "expectedVersion": 4
    }
  },
  "class": {
    "classAlias": "CL.CodexTest",
    "name": "Codex Test",
    "objectTypeAlias": "OT.CodexTest",
      "namePropertyAlias": "PD.Title",
    "propertyAssociations": [
      { "propertyAlias": "PD.Title", "required": true }
    ],
    "workflowAlias": "",
    "forceWorkflow": false
  },
  "valueList": {
    "entity": "valueList",
    "valueListAlias": "VL.CodexTest",
    "nameSingular": "Test value",
    "namePlural": "Test values"
  },
  "valueListItem": {
    "entity": "item",
    "valueListAlias": "VL.CodexTest",
    "itemId": 12,
    "name": "Updated value"
  },
  "workflow": {
    "workflowAlias": "WF.CodexTest",
    "name": "Codex Test",
    "description": "",
    "states": [
      { "stateAlias": "WFS.CodexTest.Draft", "name": "Draft" }
    ],
    "transitions": []
  },
  "view": {
    "name": "Codex Test",
    "visible": true,
    "excludeDeleted": true,
    "classAlias": "CL.CodexTest"
  }
}

Object read/write candidates may use the reserved portable identifier MFBuiltInPropertyDef.NameOrTitle. The adapter resolves it through the M-Files built-in enum, never through a copied vault-local numeric ID. A custom class still requires an aliased associated text property as its name property; the built-in Name or title property cannot fill that structural role.

Object reads use identity { "objectTypeAlias": "...", "objectId": 42, "propertyAliases": ["..."] }. Value-list reads use valueListAlias, optional itemId, and maxItems (capped at 500). View updates/deletes use a vault-local viewId or guid. Object-type reads use objectTypeAlias and return icon metadata only. Property reads use propertyAlias and return dependency/filter/automatic-value fingerprints. Class and workflow reads use the snapshot, summary, analyzer, and comparison tools.

CRUD v2 intentionally excludes file uploads, permanent object destruction, personal views, and arbitrary view expressions. Property migration blocks VBScript-bearing definitions and typed lookup filters until their semantic dependencies can be remapped. Class migration blocks associated properties with those advanced dependencies; migrate them separately first. Object-type migration excludes real/built-in types and unresolved property references. Value-list migration excludes hierarchical lists and deleted items. Workflow migration currently supports only simple portable workflows: compatible predefined-group ACLs, aliased states, no state actions, no conditions or scripts, and manual transitions without criteria. Complex workflow dependency remapping remains fail-closed and requires a separate reviewed capability increment. "# MFiles-MCP-Server"