synartesis 0.1.0

package/manifests/git.yaml

@@ -0,0 +1,77 @@
+# Policy for mcp-server-git, the official git server, run through uvx.
+#
+# Verified against the real server on a real repository.
+#
+# The finding worth carrying away from writing this one: nearly every read this
+# server offers answers in prose meant for a person -- git_status says "On
+# branch main", not {"branch": "main"}. A snapshot is only useful if something
+# can be read back out of it by path, so almost nothing here can be inverted
+# from a captured state, however reversible the underlying git operation is.
+# The limit is the server's, not git's, and pretending otherwise would produce
+# a policy that reports work as undone without having undone it.
+version: 1
+
+servers:
+  git:
+    command: uvx
+    args: ["--from", "mcp-server-git", "mcp-server-git"]
+
+tools:
+  # --- reads -------------------------------------------------------------
+  - match: "git.git_status"
+    class: readonly
+  - match: "git.git_diff"
+    class: readonly
+  - match: "git.git_diff_staged"
+    class: readonly
+  - match: "git.git_diff_unstaged"
+    class: readonly
+  - match: "git.git_log"
+    class: readonly
+  - match: "git.git_show"
+    class: readonly
+  - match: "git.git_branch"
+    class: readonly
+
+  # --- the index ---------------------------------------------------------
+
+  # git_reset here unstages everything, not only what this call staged, so
+  # undoing an add can unstage work a person staged by hand beforehand. It is
+  # recorded as a compensation for that reason, and undo says so.
+  - match: "git.git_add"
+    class: compensable
+    inverse:
+      tool: "git.git_reset"
+      args:
+        repo_path: "$.repo_path"
+
+  # Unstaging destroys nothing: every change is still in the working tree, and
+  # re-staging is one command. Gating it would spend a person's attention on
+  # the cheapest operation here and leave less of it for the commit below.
+  - match: "git.git_reset"
+    class: irreversible
+    gate: never
+
+  # --- history -----------------------------------------------------------
+
+  # This server offers no reset, no revert and no way to move a branch, so
+  # nothing it exposes can take a commit back. Held for a person.
+  - match: "git.git_commit"
+    class: irreversible
+    gate: always
+
+  # No delete-branch tool exists here either. `git branch -d` removes one by
+  # hand in a second, which is precisely the sentence undo cannot say for you.
+  - match: "git.git_create_branch"
+    class: irreversible
+    gate: always
+
+  # Checking out changes no history and destroys nothing: git refuses outright
+  # when the working tree would be lost. It cannot be undone through this
+  # server because no read here reports the current branch as data, so it is
+  # recorded honestly as irreversible and deliberately not gated. A gate on
+  # every branch switch is a gate people learn to approve without reading, and
+  # that costs more than it buys on the commit above.
+  - match: "git.git_checkout"
+    class: irreversible
+    gate: never

package/manifests/github.yaml

@@ -0,0 +1,175 @@
+# Policy for GitHub's MCP server.
+#
+# NOT verified against a live account. Everything here is derived from GitHub's
+# documented API shapes, which is exactly the position the filesystem policy was
+# in before it met a real server and turned out to be wrong in one place. Run
+# `synartesis check --manifest manifests/github.yaml` against your own token
+# before trusting it, and expect to correct at least one field.
+#
+# The npm package @modelcontextprotocol/server-github is deprecated. The
+# supported server is github/github-mcp-server. Synartesis speaks stdio only,
+# so use the local binary rather than GitHub's hosted remote server.
+#
+# The honest limit of this adapter: GitHub has no ordinary-scope delete for most
+# things it creates. An issue can be closed but not un-created; a comment is
+# gone only if the author removes it; a published release stays published.
+# Anything that puts a permanent, publicly visible record into the world is
+# gated rather than dressed up as reversible.
+version: 1
+
+servers:
+  github:
+    command: github-mcp-server
+    args: ["stdio"]
+    # Read from your shell; never written into this file.
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+
+tools:
+  # --- reads -------------------------------------------------------------
+  - match: "github.get_*"
+    class: readonly
+  - match: "github.list_*"
+    class: readonly
+  - match: "github.search_*"
+    class: readonly
+
+  # --- issues ------------------------------------------------------------
+
+  # An issue cannot be deleted through the API, only closed. Closing is not
+  # the same as never having existed: people were notified.
+  - match: "github.create_issue"
+    class: irreversible
+    gate: always
+
+  # get_issue returns labels and assignees as objects while update_issue takes
+  # bare names, so the inverse projects the one field it needs out of each.
+  # `[]` reads the same key from every element and does nothing else; it is
+  # still a path, not a transform.
+  - match: "github.update_issue"
+    class: reversible
+    snapshot:
+      tool: "github.get_issue"
+      args:
+        owner: "$.owner"
+        repo: "$.repo"
+        issue_number: "$.issue_number"
+    inverse:
+      tool: "github.update_issue"
+      args:
+        owner: "$.owner"
+        repo: "$.repo"
+        issue_number: "$.issue_number"
+        title: "$snapshot.title"
+        body: "$snapshot.body"
+        state: "$snapshot.state"
+        labels: "$snapshot.labels[].name"
+        assignees: "$snapshot.assignees[].login"
+
+  - match: "github.add_issue_comment"
+    class: irreversible
+    gate: always
+
+  # --- pull requests -----------------------------------------------------
+  - match: "github.create_pull_request"
+    class: irreversible
+    gate: always
+
+  - match: "github.update_pull_request"
+    class: reversible
+    snapshot:
+      tool: "github.get_pull_request"
+      args:
+        owner: "$.owner"
+        repo: "$.repo"
+        pull_number: "$.pull_number"
+    inverse:
+      tool: "github.update_pull_request"
+      args:
+        owner: "$.owner"
+        repo: "$.repo"
+        pull_number: "$.pull_number"
+        title: "$snapshot.title"
+        body: "$snapshot.body"
+        state: "$snapshot.state"
+
+  - match: "github.merge_pull_request"
+    class: irreversible
+    gate: always
+  - match: "github.create_pull_request_review"
+    class: irreversible
+    gate: always
+  - match: "github.create_and_submit_pull_request_review"
+    class: irreversible
+    gate: always
+  - match: "github.submit_pending_pull_request_review"
+    class: irreversible
+    gate: always
+
+  # A pending review is a draft only its author can see, so deleting one puts
+  # nothing into the world. Recreating it restores the draft but not the
+  # comments that were inside it, which is a compensation rather than a
+  # reversal, and undo will report it as unverified.
+  - match: "github.delete_pending_pull_request_review"
+    class: compensable
+    inverse:
+      tool: "github.create_pending_pull_request_review"
+      args:
+        owner: "$.owner"
+        repo: "$.repo"
+        pull_number: "$.pull_number"
+
+  - match: "github.create_pending_pull_request_review"
+    class: compensable
+    inverse:
+      tool: "github.delete_pending_pull_request_review"
+      args:
+        owner: "$.owner"
+        repo: "$.repo"
+        pull_number: "$.pull_number"
+
+  # --- file contents -----------------------------------------------------
+
+  # The sha must be the blob being replaced at the moment of the revert, which
+  # is the one this very call created, not the one it replaced. Passing
+  # $snapshot.sha here is the natural mistake and GitHub rejects it as a
+  # conflict.
+  - match: "github.create_or_update_file"
+    class: reversible
+    snapshot:
+      tool: "github.get_file_contents"
+      args:
+        owner: "$.owner"
+        repo: "$.repo"
+        path: "$.path"
+        ref: "$.branch"
+    inverse:
+      tool: "github.create_or_update_file"
+      args:
+        owner: "$.owner"
+        repo: "$.repo"
+        path: "$.path"
+        branch: "$.branch"
+        content: "$snapshot.content"
+        sha: "$result.content.sha"
+        message: "Revert agent change to $.path"
+
+  # A multi-file push is one commit touching many paths. This format captures
+  # one pre-read per action, not one per path, so there is nothing honest to
+  # restore from.
+  - match: "github.push_files"
+    class: irreversible
+    gate: always
+
+  - match: "github.create_branch"
+    class: irreversible
+    gate: always
+  - match: "github.fork_repository"
+    class: irreversible
+    gate: always
+  - match: "github.create_repository"
+    class: irreversible
+    gate: always
+  - match: "github.create_release"
+    class: irreversible
+    gate: always

package/manifests/memory.yaml

@@ -0,0 +1,96 @@
+# Policy for @modelcontextprotocol/server-memory, the knowledge graph an agent
+# keeps about you between sessions.
+#
+# Verified against the real server: every tool named here was listed by it, and
+# the shapes below were read off its own responses rather than from docs.
+#
+# This is the server the taxonomy fits best. Almost everything it does has an
+# exact opposite sitting next to it in the same toolbox, which is what
+# compensable means. Two things do not, and they are gated rather than
+# approximated.
+version: 1
+
+servers:
+  memory:
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-memory"]
+    # Where the graph lives. Point it wherever your client already points it,
+    # or the agent will remember into a different file than it reads from.
+    env:
+      MEMORY_FILE_PATH: "${MEMORY_FILE_PATH}"
+
+tools:
+  # --- reads -------------------------------------------------------------
+  - match: "memory.read_graph"
+    class: readonly
+  - match: "memory.search_nodes"
+    class: readonly
+  - match: "memory.open_nodes"
+    class: readonly
+
+  # --- writes ------------------------------------------------------------
+
+  # The inverse names the result rather than the arguments, and the difference
+  # matters: this server silently ignores an entity that already exists, so
+  # undoing by argument would delete a Grace who was there long before the
+  # agent ran. The result carries only what was actually created.
+  #
+  # $result.entities, not $result: this server answers with both a text block
+  # holding a bare array and a structuredContent object wrapping it, and
+  # structured data wins over re-parsed text. Written against the text block,
+  # the first version of this policy resolved to nothing and undo halted. It is
+  # the same mistake the filesystem policy made, and the reason neither of them
+  # can be trusted until it has met a real server.
+  #
+  # $result is the structured block, not the text one, and here the two
+  # disagree: the text is a bare list of entities while structuredContent wraps
+  # it as {"entities": [...]}. The structured block is the machine-readable
+  # contract, so that is the one a path walks. Writing $result[].name here is
+  # the natural mistake, and it was the first thing this policy got wrong
+  # against the live server.
+  - match: "memory.create_entities"
+    class: compensable
+    inverse:
+      tool: "memory.delete_entities"
+      args:
+        entityNames: "$result.entities[].name"
+
+  - match: "memory.create_relations"
+    class: compensable
+    inverse:
+      tool: "memory.delete_relations"
+      args:
+        relations: "$result.relations"
+
+  # The one place this policy over-reaches, and it is written down rather than
+  # hidden: delete_relations answers in prose, so the inverse has to work from
+  # the arguments. Undoing it re-creates every relation the call named,
+  # including any that were already absent when it ran.
+  - match: "memory.delete_relations"
+    class: compensable
+    inverse:
+      tool: "memory.create_relations"
+      args:
+        relations: "$.relations"
+
+  # Deleting an entity also deletes every relation touching it. open_nodes can
+  # capture both beforehand, but a policy declares one inverse, and one call
+  # cannot put back both the entities and their relations. Restoring half of a
+  # graph and reporting it as undone is the exact failure this product exists
+  # to prevent, so it asks instead.
+  - match: "memory.delete_entities"
+    class: irreversible
+    gate: always
+
+  # add_observations and delete_observations are exact opposites that disagree
+  # about what to call the same field: one takes `observations[].contents`, the
+  # other `deletions[].observations`. A path can read a field and cannot rename
+  # one, and the manifest is deliberately not a language, so this inverse
+  # cannot be written here at all. That is a limit of the format, stated rather
+  # than papered over.
+  - match: "memory.add_observations"
+    class: irreversible
+    gate: always
+  - match: "memory.delete_observations"
+    class: irreversible
+    gate: always

package/manifests/toy-crm.yaml

@@ -0,0 +1,66 @@
+# Policy for the toy CRM fixture. Every class in the taxonomy appears here, so
+# this doubles as the worked example of the manifest format.
+version: 1
+
+servers:
+  crm:
+    command: node
+    args: ["dist/toy-crm.js"]
+
+tools:
+  - match: "crm.get_customer"
+    class: readonly
+
+  # The id is assigned by the server, so it is only knowable from the result.
+  - match: "crm.create_customer"
+    class: compensable
+    inverse:
+      tool: "crm.delete_customer"
+      args:
+        id: "$result.id"
+
+  # A patch, so the inverse has to restore every field rather than re-apply the
+  # patch: fields the agent did not touch must still come back unchanged if the
+  # same record is updated twice in one run.
+  - match: "crm.update_customer"
+    class: reversible
+    snapshot:
+      tool: "crm.get_customer"
+      args:
+        id: "$.id"
+    inverse:
+      tool: "crm.update_customer"
+      args:
+        id: "$.id"
+        name: "$snapshot.name"
+        email: "$snapshot.email"
+        plan: "$snapshot.plan"
+        notes: "$snapshot.notes"
+
+  # Reversible rather than irreversible because the pre-read captures the whole
+  # record and restore_customer puts it back under its original id.
+  - match: "crm.delete_customer"
+    class: reversible
+    snapshot:
+      tool: "crm.get_customer"
+      args:
+        id: "$.id"
+    inverse:
+      tool: "crm.restore_customer"
+      args:
+        id: "$snapshot.id"
+        name: "$snapshot.name"
+        email: "$snapshot.email"
+        plan: "$snapshot.plan"
+        notes: "$snapshot.notes"
+
+  - match: "crm.restore_customer"
+    class: compensable
+    inverse:
+      tool: "crm.delete_customer"
+      args:
+        id: "$.id"
+
+  - match: "crm.send_email"
+    class: irreversible
+    gate: always

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "synartesis",
+  "version": "0.1.0",
+  "description": "An undo layer for AI agents.",
+  "type": "module",
+  "private": false,
+  "author": "Arhaan (https://github.com/ArhaanDev24)",
+  "license": "MIT",
+  "homepage": "https://github.com/ArhaanDev24/Synartesis",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArhaanDev24/Synartesis.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ArhaanDev24/Synartesis/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "undo",
+    "rollback",
+    "ai-agents",
+    "saga"
+  ],
+  "bin": {
+    "synartesis": "dist/cli.js",
+    "synartesis-proxy": "dist/proxy.js"
+  },
+  "files": [
+    "dist",
+    "manifests",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "pretest": "tsup --silent",
+    "demo": "tsup --silent && ./demo/filesystem-demo.sh",
+    "demo:memory": "tsup --silent && ./demo/memory-demo.sh",
+    "prepublishOnly": "tsup"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "better-sqlite3": "^13.0.3",
+    "pino": "^10.3.1",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/server-filesystem": "^2026.7.10",
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^26.2.0",
+    "eslint": "^10.8.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.67.0",
+    "vitest": "^4.1.11"
+  },
+  "packageManager": "pnpm@9.15.9+sha512.68046141893c66fad01c079231128e9afb89ef87e2691d69e4d40eee228988295fd4682181bae55b58418c3a253bde65a505ec7c5f9403ece5cc3cd37dcf2531"
+}