Plandex Server — Context & Diffs

naftiko: 1.0.0-alpha2
info:
  label: Plandex Server — Context & Diffs
  description: 'Plandex Server — Context & Diffs. Manages files, directories, URLs, notes, and images loaded into a plan branch, and operates on pending diffs (apply, reject, list). Self-contained Naftiko capability covering the context/diff surface of the Plandex REST API.'
  tags:
    - Plandex
    - Context
    - Diffs
    - File Map
  created: '2026-05-29'
  modified: '2026-05-29'
binds:
  - namespace: env
    keys:
      PLANDEX_BASE_URL: PLANDEX_BASE_URL
      PLANDEX_API_TOKEN: PLANDEX_API_TOKEN
capability:
  consumes:
    - type: http
      namespace: plandex-context-diffs
      baseUri: '{{env.PLANDEX_BASE_URL}}'
      description: Plandex Server context and diffs surface. Defaults to http://localhost:8099 for local-mode deployments.
      resources:
        - name: plans-planId-branch-context
          path: /plans/{planId}/{branch}/context
          operations:
            - name: listcontext
              method: GET
              description: List Context
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: loadcontext
              method: POST
              description: Load Context
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: updatecontext
              method: PUT
              description: Update Context
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: deletecontext
              method: DELETE
              description: Delete Context
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: plans-planId-branch-context-body
          path: /plans/{planId}/{branch}/context/{contextId}/body
          operations:
            - name: getcontextbody
              method: GET
              description: Get Context Body
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: plans-planId-branch-diffs
          path: /plans/{planId}/{branch}/diffs
          operations:
            - name: getplandiffs
              method: GET
              description: Get Plan Diffs
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: plans-planId-branch-apply
          path: /plans/{planId}/{branch}/apply
          operations:
            - name: applyplan
              method: PATCH
              description: Apply Plan Changes
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: plans-planId-branch-reject-all
          path: /plans/{planId}/{branch}/reject_all
          operations:
            - name: rejectallchanges
              method: PATCH
              description: Reject All Plan Changes
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: plans-planId-branch-reject-file
          path: /plans/{planId}/{branch}/reject_file
          operations:
            - name: rejectfile
              method: PATCH
              description: Reject Plan File Change
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: plans-planId-branch-reject-files
          path: /plans/{planId}/{branch}/reject_files
          operations:
            - name: rejectfiles
              method: PATCH
              description: Reject Multiple File Changes
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: file-map
          path: /file_map
          operations:
            - name: getfilemap
              method: POST
              description: Get File Map
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
      authentication:
        type: bearer
        token: '{{env.PLANDEX_API_TOKEN}}'
  exposes:
    - type: rest
      namespace: plandex-context-diffs-rest
      port: 8080
      description: REST adapter for Plandex Server context & diffs. One Spectral-compliant resource per consumed operation, prefixed with /v1.
      resources:
        - path: /v1/plans/{planid}/{branch}/context
          name: plan-context
          description: REST surface for plan context.
          operations:
            - method: GET
              name: listcontext
              description: List Context
              call: plandex-context-diffs.listcontext
              outputParameters:
                - type: object
                  mapping: $.
            - method: POST
              name: loadcontext
              description: Load Context
              call: plandex-context-diffs.loadcontext
              outputParameters:
                - type: object
                  mapping: $.
            - method: PUT
              name: updatecontext
              description: Update Context
              call: plandex-context-diffs.updatecontext
              outputParameters:
                - type: object
                  mapping: $.
            - method: DELETE
              name: deletecontext
              description: Delete Context
              call: plandex-context-diffs.deletecontext
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/plans/{planid}/{branch}/context/{contextid}/body
          name: plan-context-body
          description: REST surface for context item body.
          operations:
            - method: GET
              name: getcontextbody
              description: Get Context Body
              call: plandex-context-diffs.getcontextbody
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/plans/{planid}/{branch}/diffs
          name: plan-diffs
          description: REST surface for plan diffs.
          operations:
            - method: GET
              name: getplandiffs
              description: Get Plan Diffs
              call: plandex-context-diffs.getplandiffs
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/plans/{planid}/{branch}/apply
          name: plan-apply
          description: REST surface for plan apply.
          operations:
            - method: PATCH
              name: applyplan
              description: Apply Plan Changes
              call: plandex-context-diffs.applyplan
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/plans/{planid}/{branch}/reject-all
          name: plan-reject-all
          description: REST surface for plan reject-all.
          operations:
            - method: PATCH
              name: rejectallchanges
              description: Reject All Plan Changes
              call: plandex-context-diffs.rejectallchanges
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/plans/{planid}/{branch}/reject-file
          name: plan-reject-file
          description: REST surface for plan reject single file.
          operations:
            - method: PATCH
              name: rejectfile
              description: Reject Plan File Change
              call: plandex-context-diffs.rejectfile
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/plans/{planid}/{branch}/reject-files
          name: plan-reject-files
          description: REST surface for plan reject multiple files.
          operations:
            - method: PATCH
              name: rejectfiles
              description: Reject Multiple File Changes
              call: plandex-context-diffs.rejectfiles
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/file-map
          name: file-map
          description: REST surface for tree-sitter file map generation.
          operations:
            - method: POST
              name: getfilemap
              description: Get File Map
              call: plandex-context-diffs.getfilemap
              outputParameters:
                - type: object
                  mapping: $.
    - type: mcp
      namespace: plandex-context-diffs-mcp
      port: 9090
      transport: http
      description: MCP adapter for Plandex Server context & diffs. One tool per consumed operation, routed inline through this capability's consumes block.
      tools:
        - name: list-context
          description: List Context
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: plandex-context-diffs.listcontext
          outputParameters:
            - type: object
              mapping: $.
        - name: load-context
          description: Load Context
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: plandex-context-diffs.loadcontext
          outputParameters:
            - type: object
              mapping: $.
        - name: update-context
          description: Update Context
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: plandex-context-diffs.updatecontext
          outputParameters:
            - type: object
              mapping: $.
        - name: delete-context
          description: Delete Context
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: plandex-context-diffs.deletecontext
          outputParameters:
            - type: object
              mapping: $.
        - name: get-context-body
          description: Get Context Body
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: plandex-context-diffs.getcontextbody
          outputParameters:
            - type: object
              mapping: $.
        - name: get-plan-diffs
          description: Get Plan Diffs
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: plandex-context-diffs.getplandiffs
          outputParameters:
            - type: object
              mapping: $.
        - name: apply-plan
          description: Apply Plan Changes
          hints:
            readOnly: false
            destructive: true
            idempotent: false
          call: plandex-context-diffs.applyplan
          outputParameters:
            - type: object
              mapping: $.
        - name: reject-all-changes
          description: Reject All Plan Changes
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: plandex-context-diffs.rejectallchanges
          outputParameters:
            - type: object
              mapping: $.
        - name: reject-file
          description: Reject Plan File Change
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: plandex-context-diffs.rejectfile
          outputParameters:
            - type: object
              mapping: $.
        - name: reject-files
          description: Reject Multiple File Changes
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: plandex-context-diffs.rejectfiles
          outputParameters:
            - type: object
              mapping: $.
        - name: get-file-map
          description: Get File Map
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: plandex-context-diffs.getfilemap
          outputParameters:
            - type: object
              mapping: $.