Core — vcs

naftiko: 1.0.0-alpha2
info:
  label: Core — vcs
  description: 'Core — vcs. 6 operations. Lead operation: Get and save a user Bitbucket token to their database object. This allows subsequent queries for Bitbucket data from the user scope.. Self-contained Naftiko capability covering one business surface.'
  tags:
  - Scalar
  - vcs
  created: '2026-05-20'
  modified: '2026-05-20'
binds:
- namespace: env
  keys:
    SCALAR_API_KEY: SCALAR_API_KEY
capability:
  consumes:
  - type: http
    namespace: core-vcs
    baseUri: https://example.com
    description: Core — vcs business capability. Self-contained, no shared references.
    resources:
    - name: vcs-bitbucket-authorize
      path: /vcs/bitbucket/authorize
      operations:
      - name: getvcsbitbucketauthorize
        method: GET
        description: Get and save a user Bitbucket token to their database object. This allows subsequent queries for Bitbucket data from the user scope.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: code
          in: query
          type: string
          description: query parameter code.
          required: true
        - name: state
          in: query
          type: string
          description: query parameter state.
          required: true
    - name: vcs-bitbucket-link-initiate
      path: /vcs/bitbucket/link/initiate
      operations:
      - name: getvcsbitbucketlinkinitiate
        method: GET
        description: Issue a signed OAuth state token for the Bitbucket user-authorization flow and return the Bitbucket authorize URL the client should redirect
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: redirect
          in: query
          type: string
          description: query parameter redirect.
    - name: vcs-bitbucket-workspaces
      path: /vcs/bitbucket/workspaces
      operations:
      - name: getvcsbitbucketworkspaces
        method: GET
        description: List the calling user's Bitbucket workspaces and the repositories they can write to. Used by the link-to-Bitbucket UI.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters: []
    - name: vcs-bitbucket-docs-project-uid-branches
      path: /vcs/bitbucket/docs-project/{uid}/branches
      operations:
      - name: getvcsbitbucketdocsprojectuidbranches
        method: GET
        description: 'List branches on the Bitbucket repo backing a `provider: ''bitbucket''` DocsProject. Supports prefix search via the `query` param.'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: uid
          in: path
          type: string
          description: path parameter uid.
          required: true
        - name: query
          in: query
          type: string
          description: query parameter query.
        - name: page
          in: query
          type: number
          description: query parameter page.
          required: true
        - name: perPage
          in: query
          type: number
          description: query parameter perPage.
          required: true
    - name: vcs-bitbucket-disconnect-account
      path: /vcs/bitbucket/disconnect-account
      operations:
      - name: postvcsbitbucketdisconnectaccount
        method: POST
        description: Wipe the calling user's Bitbucket OAuth tokens. Any DocsProjects this user linked will lose their token and need to be re-linked or have the
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: vcs-github-disconnect-account
      path: /vcs/github/disconnect-account
      operations:
      - name: postvcsgithubdisconnectaccount
        method: POST
        description: Wipe the calling user's GitHub OAuth tokens. Any DocsProjects this user linked will lose their token; the user can reconnect at any time.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
  exposes:
  - type: rest
    namespace: core-vcs-rest
    port: 8080
    description: REST adapter for Core — vcs. One resource per consumed operation, prefixed with /v1.
    resources:
    - path: /v1/vcs/bitbucket/authorize
      name: vcs-bitbucket-authorize
      description: REST surface for vcs-bitbucket-authorize.
      operations:
      - method: GET
        name: getvcsbitbucketauthorize
        description: Get and save a user Bitbucket token to their database object. This allows subsequent queries for Bitbucket data from the user scope.
        call: core-vcs.getvcsbitbucketauthorize
        with:
          code: rest.code
          state: rest.state
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/vcs/bitbucket/link/initiate
      name: vcs-bitbucket-link-initiate
      description: REST surface for vcs-bitbucket-link-initiate.
      operations:
      - method: GET
        name: getvcsbitbucketlinkinitiate
        description: Issue a signed OAuth state token for the Bitbucket user-authorization flow and return the Bitbucket authorize URL the client should redirect
        call: core-vcs.getvcsbitbucketlinkinitiate
        with:
          redirect: rest.redirect
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/vcs/bitbucket/workspaces
      name: vcs-bitbucket-workspaces
      description: REST surface for vcs-bitbucket-workspaces.
      operations:
      - method: GET
        name: getvcsbitbucketworkspaces
        description: List the calling user's Bitbucket workspaces and the repositories they can write to. Used by the link-to-Bitbucket UI.
        call: core-vcs.getvcsbitbucketworkspaces
        with: {}
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/vcs/bitbucket/docs-project/{uid}/branches
      name: vcs-bitbucket-docs-project-uid-branches
      description: REST surface for vcs-bitbucket-docs-project-uid-branches.
      operations:
      - method: GET
        name: getvcsbitbucketdocsprojectuidbranches
        description: 'List branches on the Bitbucket repo backing a `provider: ''bitbucket''` DocsProject. Supports prefix search via the `query` param.'
        call: core-vcs.getvcsbitbucketdocsprojectuidbranches
        with:
          uid: rest.uid
          query: rest.query
          page: rest.page
          perPage: rest.perPage
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/vcs/bitbucket/disconnect-account
      name: vcs-bitbucket-disconnect-account
      description: REST surface for vcs-bitbucket-disconnect-account.
      operations:
      - method: POST
        name: postvcsbitbucketdisconnectaccount
        description: Wipe the calling user's Bitbucket OAuth tokens. Any DocsProjects this user linked will lose their token and need to be re-linked or have the
        call: core-vcs.postvcsbitbucketdisconnectaccount
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/vcs/github/disconnect-account
      name: vcs-github-disconnect-account
      description: REST surface for vcs-github-disconnect-account.
      operations:
      - method: POST
        name: postvcsgithubdisconnectaccount
        description: Wipe the calling user's GitHub OAuth tokens. Any DocsProjects this user linked will lose their token; the user can reconnect at any time.
        call: core-vcs.postvcsgithubdisconnectaccount
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: core-vcs-mcp
    port: 9090
    transport: http
    description: MCP adapter for Core — vcs. One tool per consumed operation, routed inline through this capability's consumes block.
    tools:
    - name: scalar-getvcsbitbucketauthorize
      description: Get and save a user Bitbucket token to their database object. This allows subsequent queries for Bitbucket data from the user scope.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: core-vcs.getvcsbitbucketauthorize
      with:
        code: tools.code
        state: tools.state
      outputParameters:
      - type: object
        mapping: $.
    - name: scalar-getvcsbitbucketlinkinitiate
      description: Issue a signed OAuth state token for the Bitbucket user-authorization flow and return the Bitbucket authorize URL the client should redirect
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: core-vcs.getvcsbitbucketlinkinitiate
      with:
        redirect: tools.redirect
      outputParameters:
      - type: object
        mapping: $.
    - name: scalar-getvcsbitbucketworkspaces
      description: List the calling user's Bitbucket workspaces and the repositories they can write to. Used by the link-to-Bitbucket UI.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: core-vcs.getvcsbitbucketworkspaces
      with: {}
      outputParameters:
      - type: object
        mapping: $.
    - name: scalar-getvcsbitbucketdocsprojectuidbranches
      description: 'List branches on the Bitbucket repo backing a `provider: ''bitbucket''` DocsProject. Supports prefix search via the `query` param.'
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: core-vcs.getvcsbitbucketdocsprojectuidbranches
      with:
        uid: tools.uid
        query: tools.query
        page: tools.page
        perPage: tools.perPage
      outputParameters:
      - type: object
        mapping: $.
    - name: scalar-postvcsbitbucketdisconnectaccount
      description: Wipe the calling user's Bitbucket OAuth tokens. Any DocsProjects this user linked will lose their token and need to be re-linked or have the
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: core-vcs.postvcsbitbucketdisconnectaccount
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: scalar-postvcsgithubdisconnectaccount
      description: Wipe the calling user's GitHub OAuth tokens. Any DocsProjects this user linked will lose their token; the user can reconnect at any time.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: core-vcs.postvcsgithubdisconnectaccount
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.