Tool reference

Get started

Installing the npm package auto-detects every MCP client on your machine - Claude Code, Claude Desktop, Cursor, and Codex - and wires each one up at user scope. Quick walks through the install + restart flow. Manual gives you the raw config snippet for each client if you’d rather wire it up by hand.

Context graph

Everything Casper exposes - every tool, every answer - is backed by a single in-memory data structure called the context graph. It’s a typed view of your Terraform infrastructure that the agent queries instead of reading raw files.

What it is

The graph is a directed, attributed graph held in memory by the MCP server for the duration of the session. Every Terraform concept becomes a typed entity:

• Nodes. Resources, data sources, module calls, and module definitions. Each carries its full attribute set, tags, and source path.
• Edges. References, depends_on relationships, and module input/output wiring. Edges are typed and traversable in both directions.
• Conventions. An aggregated view of how resource types are configured across the repo: common args, modal values, recurring tag keys.
• Policies. Rules from .rego files (preferred) or .casper/policies.yaml evaluated against the graph; violations attach to affected resources.

How it’s made

On startup Casper runs a four-stage pipeline against the directory you point it at:

1. 01
   Scan

   Walk the tree, collect every .tf and .tfstate file (skipping vendored modules and .terraform caches).

2. 02
   Parse

   Use HashiCorp's HCL parser to extract resource blocks, attributes, references, and module calls into typed records.

3. 03
   Link

   Resolve cross-file references and depends_on into directed edges. Module calls are wired to their definitions.

4. 04
   Index

   Compute conventions, evaluate policies, and build the lookup tables that power every MCP tool.

Why a graph

Casper resolves resources, references, modules, policies, and state once at parse time, then tools query the graph instead of rereading raw Terraform. Token cost stays flat regardless of repo size, dependency walks are O(1) per hop, and policies and drift detection have a structured surface to evaluate against.

Bring your own policies, or use simple YAML

Casper checks org policy on every simulate_impact call. If the repo has any .rego files, they’re the source of truth (compatible with existing Conftest libraries). Otherwise Casper falls back to a simple YAML format in .casper/policies.yaml. Zero config either way.

1. 01
   Discover

   On startup Casper walks the repo for .rego files; falls back to .casper/policies.yaml when none exist.

2. 02
   Compile

   Rego policies are compiled once via the embedded OPA engine. YAML rules are parsed into typed checks.

3. 03
   Check

   Every simulate_impact and dump_graph call evaluates the loaded engine against affected resources.

4. 04
   Correct

   The agent reads policy_violations[] in the response and fixes its own draft before applying.

Rego (OPA) support

Casper recursively scans the repo for *.rego files (skipping .git, .terraform, node_modules, vendor, testdata). Every file becomes a loaded policy. The embedded OPA evaluator compiles them once at startup. As soon as any .rego file is found, YAML argument rules are disabled; workflow rules in .casper/policies.yaml keep firing.

Example policy

package policy

deny[msg] {
  input.type == "aws_s3_bucket"
  input.attributes.acl == "public-read"
  msg := sprintf("s3 bucket %s is public-read", [input.identifier])
}

Input shape (per resource)

{
  "type":       "aws_s3_bucket",
  "identifier": "aws_s3_bucket.data",
  "attributes": { "bucket": "my-bucket", "acl": "private", ... },
  "tags":       { "env": "prod", "owner": "platform" }
}

YAML argument rules

For teams that aren’t already on OPA, Casper ships a simple YAML format. Each rule names a Terraform resource type, declares one or more argument constraints, and gives a human-readable message the agent can quote back when it asks you to confirm a fix. Loaded only when no .rego files exist in the repo.

policies:
  - id: rds-deletion-protection
    resource: aws_db_instance
    rules:
      - arg: deletion_protection
        must_equal: "true"
    message: "RDS instances must have deletion_protection enabled"

  - id: rds-backup-retention
    resource: aws_db_instance
    rules:
      - arg: backup_retention_period
        min_value: 7
    message: "RDS instances must retain backups for at least 7 days"

  - id: everything-needs-an-owner
    resource: "*"             # apply to every resource type
    rules:
      - arg: owner
        required: true
    message: "All resources must have an owner argument"

Supported rule types

Multiple rules in one policy AND together. Each violation appears as its own entry in the response, so the agent gets full diagnostics on the first call.

Workflow rules

Workflow rules don’t enforce arguments. They classify the change itself and route it to a decision: allow, require_approval, require_security_review, or block. The agent reads the decision and follows it.

workflow_rules:
  - id: prod-database-destroy-block
    when:
      env: prod
      resource_type_family: database
      operation: destroy
    decision: block
    reason: "DB destroys in prod require a manual ticket"

  - id: prod-changes-require-approval
    when:
      env: prod
      operation: [create, modify, destroy]
    decision: require_approval

  - id: iam-needs-security-review
    when:
      resource_type_family: iam
    decision: require_security_review

A rule fires when every non-empty field in when: matches. Empty fields are wildcards. For a single change the strictest decision wins overall: block > require_security_review > require_approval > allow.

How violations surface to the agent

Every simulate_impact response carries a policy_violations[] array and a workflow_decision object. The agent’s system prompt tells it to read these before presenting the change to you.

{
  "summary": "1 created, 0 modified, 0 in blast radius",
  "created": [...],
  "policy_violations": [
    {
      "policy_id": "rds-deletion-protection",
      "resource": "aws_db_instance.orders_replica",
      "type": "aws_db_instance",
      "message": "RDS instances must have deletion_protection enabled",
      "details": "argument \"deletion_protection\" must be \"true\" (not set)"
    }
  ],
  "workflow_decision": {
    "decision": "require_approval",
    "matched_rules": [
      { "id": "prod-changes-require-approval", "reason": "env=prod, operation=create" }
    ],
    "blocked": false
  }
}

When Casper needs AWS access

Casper builds its graph from .tf code alone with zero credentials. Two tools want more: drift detection and remote state fetching. Both are read-only.

No other tool touches AWS. Everything else runs against the in-memory graph.

How Casper authenticates

Casper reads AWS credentials from environment variables. Set one of the two standard sets below and Casper inherits them automatically — same as aws cli or Terraform.

export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
# optional, for temporary STS credentials:
export AWS_SESSION_TOKEN=...

CLI vs GUI MCP clients

CLI clients (Claude Code, Codex) inherit your shell environment, so exporting the variables in the same terminal is enough.

GUI clients (Claude Desktop, Cursor on macOS) are launched by the OS and don’t see your shell env. Put the variables in the MCP client config’s env block instead:

{
  "mcpServers": {
    "casper": {
      "command": "casper-mcp",
      "args": ["serve", "--dir", "."],
      "env": {
        "AWS_ACCESS_KEY_ID": "AKIA...",
        "AWS_SECRET_ACCESS_KEY": "..."
      }
    }
  }
}

Required permissions

Two minimal IAM policies depending on which tools you want to use. Attach both to the role (or user) Casper authenticates as.

For S3 state fetching only

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::your-state-bucket/*"
    },
    {
      "Effect": "Allow",
      "Action": "kms:Decrypt",
      "Resource": "arn:aws:kms:*:*:key/your-state-key-id"
    }
  ]
}

The kms:Decrypt statement is only needed if your state bucket uses KMS encryption (most do). Scope the resource ARN to the specific key when possible.

For describe_live_state drift detection

Cover the AWS service families Casper supports today. You can start narrow (only what your repo actually uses) and grow over time.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "rds:DescribeDBInstances",
      "rds:DescribeDBClusters",
      "rds:DescribeDBSubnetGroups",
      "ec2:DescribeSecurityGroups",
      "ec2:DescribeSubnets",
      "ec2:DescribeVpcs",
      "ec2:DescribeInstances",
      "s3:GetBucketLocation",
      "s3:GetBucketVersioning",
      "s3:GetBucketTagging",
      "iam:GetRole",
      "lambda:GetFunction",
      "eks:DescribeCluster"
    ],
    "Resource": "*"
  }]
}

AWS managed policy arn:aws:iam::aws:policy/ReadOnlyAccess also works as a coarse alternative — it’s broader than Casper needs but easy to attach.

Trust policy for assume-role

If you use Option B (assume role), the target role needs a trust policy allowing your developer identity (or CI identity) to assume it.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "AWS": "arn:aws:iam::123456789012:role/developer"
    },
    "Action": "sts:AssumeRole"
  }]
}

Config reference

The full surface area — everything Casper reads from .casper/config.yaml for AWS.

Credentials are env-only (see the previous section). The config file is just for one knob:

Example

cloud:
  aws:
    regions: [us-east-1, ap-south-1]

If you don’t need AWS at all, skip the file entirely. Casper still runs; describe_live_state returns a clear configuration-needed error and S3 backend fetches degrade to a logged failure visible in list_state_sources.