morfx

Morfx

Deterministic AST-based code transformations for AI agents, via MCP and standalone tools.

Morfx is a deterministic AST transformation engine that ships both an MCP server and standalone JSON tools. It gives AI coding agents and local automation the ability to query, transform, and safely modify code using tree-sitter AST analysis — not regex, not string matching.

Why

AI agents edit code by generating diffs or full-file rewrites. That works until it doesn't: off-by-one replacements, broken scope, wrong indentation, silent failures. Morfx solves this by operating on the actual syntax tree. Every transform is targeted by AST node, confidence-scored, and optionally staged for review before applying.

What it does

• Query — Find functions, structs, classes, methods, interfaces by type and name pattern (wildcards supported)
• Replace — Swap a matched code element with new code
• Delete — Remove a matched element cleanly
• Insert before / after — Add code relative to a target element
• Append — Smart placement at end of file or scope
• Stage / Apply / Rollback — Two-phase commit with SQLite audit trail
• Confidence scoring — Every transform gets a score with explainable factors
• Multi-language — Go, JavaScript, TypeScript, PHP, Python via tree-sitter

Modes

Morfx ships in two complementary forms:

• morfx mcp for MCP-compatible AI clients such as Claude Desktop or Codex
• Standalone binaries such as query, replace, file_query, and apply for direct local automation

For the standalone stdin/stdout contracts, see docs/standalone-tools.md. For shell-level usage patterns and TFX recipes, see docs/standalone-recipes.md.

Install

From source

git clone https://github.com/oxhq/morfx.git
cd morfx
go build -o bin/morfx ./cmd/morfx
make build-standalone

Quick install

go install github.com/oxhq/morfx/cmd/morfx@latest

Setup

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "morfx": {
      "command": "/path/to/morfx",
      "args": ["mcp"],
      "env": {
        "HOME": "/Users/you",
        "NO_COLOR": "1"
      }
    }
  }
}

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.morfx]
command = "/path/to/morfx"
args = ["mcp"]

[mcp_servers.morfx.env]
HOME = "/Users/you"
NO_COLOR = "1"

Any MCP client

Morfx speaks MCP 2025-11-25 over stdio. Point any MCP-compatible client at the binary with mcp as the subcommand.

Standalone Tools

Build them locally with:

make build-standalone

Usage examples

These are the JSON payloads your AI agent sends. You don't type these — your agent does.

Find all functions matching a pattern:

{
  "language": "go",
  "path": "/project/handlers.go",
  "query": {"type": "function", "name": "Handle*"}
}

Replace a method:

{
  "language": "php",
  "path": "/project/app/Http/Controllers/UserController.php",
  "target": {"type": "method", "name": "store"},
  "replacement": "public function store(StoreUserRequest $request): JsonResponse\n{\n    return new UserResource(User::create($request->validated()));\n}"
}

Insert a comment before a function:

{
  "language": "go",
  "path": "/project/service.go",
  "target": {"type": "function", "name": "DeleteUser"},
  "content": "// DeleteUser removes a user permanently. Use with caution."
}

Confidence scoring

Every transformation returns a confidence score (0.0–1.0) with factors:

Confidence: █████████░ 90.0%
Factors:
  +0.10 single_target — Only one match found
  -0.20 exported_api — Modifying public API

When confidence exceeds the threshold (default 0.85), transforms auto-apply. Below threshold, they stage for manual review via apply.

Configuration

morfx mcp                           # Start with defaults
morfx mcp --debug                   # Debug logging to stderr
morfx mcp --db ./my.db              # Custom SQLite path
morfx mcp --auto-threshold 0.9      # Stricter auto-apply

TFX Dogfooding

This repository now ships a root tfx.yaml so Morfx can be orchestrated through TFX as a standalone product, not only as an MCP backend.

Typical flows:

tfx --flow ci --run
tfx --flow standalone --run
tfx --flow dogfood-tfx --run
tfx --flow quality --run
tfx --flow release --lane canary --run

The standalone flow builds the local binaries and exercises query, replace, and file_query against a temporary fixture through tools/scripts/smoke-standalone.sh.

The dogfood-tfx flow targets a local checkout of oxhq/tfx through tools/scripts/dogfood-tfx.sh, running read-only queries on the real repo and a safe replacement against a temporary copy of a TFX source file. Override the target checkout with MORFX_DOGFOOD_TFX_DIR=/path/to/tfx.

Supported languages

Architecture

morfx mcp (stdio)
├── MCP Protocol (JSON-RPC 2.0, 2025-11-25 spec)
├── Tool Registry (10 tools)
├── Provider Registry
│   ├── Go provider (tree-sitter)
│   ├── JavaScript provider
│   ├── TypeScript provider
│   ├── PHP provider
│   └── Python provider
├── Base Provider (shared AST engine)
│   ├── Query (walkTree + pattern match)
│   ├── Transform (replace/delete/insert/append)
│   ├── Confidence scoring
│   └── AST cache + parser pool
├── Safety Manager (atomic writes, integrity checks)
└── Staging Manager (SQLite, stage/apply/rollback)

Development

go build ./...              # Build everything
go test ./...               # Run all tests
go test -race ./...         # Race detector
go test -cover ./...        # Coverage
make build-standalone       # Build standalone JSON tools
make smoke-standalone       # Run standalone fixture smoke tests
make verify                 # Strict local verification

License

MIT