naftiko: 1.0.0-alpha2
info:
  label: Synapse Homeserver Administration
  description: Workflow capability for administering a Synapse Matrix homeserver. Enables server administrators to manage
    users, rooms, registration, federation, and monitor server health through a unified REST and MCP interface backed by the
    Synapse Admin API.
  tags:
  - Administration
  - Federation
  - Homeserver
  - Matrix
  - Synapse
  - Users
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    SYNAPSE_ADMIN_TOKEN: SYNAPSE_ADMIN_TOKEN
capability:
  consumes:
  - type: http
    namespace: synapse-admin
    baseUri: https://matrix.example.com/_synapse/admin
    description: Synapse Admin API for homeserver management
    authentication:
      type: bearer
      token: '{{SYNAPSE_ADMIN_TOKEN}}'
    resources:
    - name: users
      path: /v2/users
      description: User account management
      operations:
      - name: list-users
        method: GET
        description: List all local users on the homeserver
        inputParameters:
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum results to return
        - name: from
          in: query
          type: integer
          required: false
          description: Pagination offset
        - name: deactivated
          in: query
          type: boolean
          required: false
          description: Include deactivated accounts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-user
        method: GET
        description: Get details about a specific user
        inputParameters:
        - name: userId
          in: path
          type: string
          required: true
          description: Matrix user ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: upsert-user
        method: PUT
        description: Create or modify a user account
        inputParameters:
        - name: userId
          in: path
          type: string
          required: true
          description: Matrix user ID
        body:
          type: json
          data:
            password: '{{tools.password}}'
            admin: '{{tools.admin}}'
            displayname: '{{tools.displayname}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: rooms
      path: /v1/rooms
      description: Room administration
      operations:
      - name: list-rooms
        method: GET
        description: List all rooms on the homeserver
        inputParameters:
        - name: search_term
          in: query
          type: string
          required: false
          description: Filter by room name or ID
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum results
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-room
        method: GET
        description: Get details about a specific room
        inputParameters:
        - name: roomId
          in: path
          type: string
          required: true
          description: Matrix room ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-room-members
        method: GET
        description: List all members of a room
        inputParameters:
        - name: roomId
          in: path
          type: string
          required: true
          description: Matrix room ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: registration-tokens
      path: /v1/registration_tokens
      description: Registration token management
      operations:
      - name: list-registration-tokens
        method: GET
        description: List all registration tokens
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: create-registration-token
        method: POST
        description: Create a new registration token
        body:
          type: json
          data:
            uses_allowed: '{{tools.usesAllowed}}'
            expiry_time: '{{tools.expiryTime}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: server
      path: /v1/server_version
      description: Server information
      operations:
      - name: get-server-version
        method: GET
        description: Get the current Synapse server version
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: synapse-homeserver-api
    description: Unified REST API for Synapse homeserver administration.
    resources:
    - path: /v1/users
      name: users
      description: User account management
      operations:
      - method: GET
        name: list-users
        description: List all users on the homeserver
        call: synapse-admin.list-users
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: create-user
        description: Create or modify a user account
        call: synapse-admin.upsert-user
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/{userId}
      name: user
      description: Individual user operations
      operations:
      - method: GET
        name: get-user
        description: Get user details
        call: synapse-admin.get-user
        with:
          userId: rest.userId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/rooms
      name: rooms
      description: Room administration
      operations:
      - method: GET
        name: list-rooms
        description: List all rooms on the homeserver
        call: synapse-admin.list-rooms
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/rooms/{roomId}/members
      name: room-members
      description: Room membership management
      operations:
      - method: GET
        name: get-room-members
        description: List all members of a room
        call: synapse-admin.get-room-members
        with:
          roomId: rest.roomId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/registration-tokens
      name: registration-tokens
      description: Registration token management
      operations:
      - method: GET
        name: list-tokens
        description: List registration tokens
        call: synapse-admin.list-registration-tokens
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: create-token
        description: Create a new registration token
        call: synapse-admin.create-registration-token
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/server/version
      name: server
      description: Server information
      operations:
      - method: GET
        name: get-version
        description: Get Synapse server version
        call: synapse-admin.get-server-version
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: synapse-homeserver-mcp
    transport: http
    description: MCP server for AI-assisted Synapse homeserver administration.
    tools:
    - name: list-users
      description: List all local users registered on the Synapse homeserver
      hints:
        readOnly: true
        openWorld: false
      call: synapse-admin.list-users
      outputParameters:
      - type: object
        mapping: $.
    - name: get-user
      description: Get detailed information about a specific Matrix user
      hints:
        readOnly: true
        openWorld: false
      call: synapse-admin.get-user
      with:
        userId: tools.userId
      outputParameters:
      - type: object
        mapping: $.
    - name: create-or-modify-user
      description: Create a new user or modify an existing user account on the homeserver
      hints:
        readOnly: false
        destructive: false
      call: synapse-admin.upsert-user
      with:
        userId: tools.userId
      outputParameters:
      - type: object
        mapping: $.
    - name: list-rooms
      description: List all rooms hosted on the Synapse homeserver with member counts
      hints:
        readOnly: true
        openWorld: false
      call: synapse-admin.list-rooms
      outputParameters:
      - type: object
        mapping: $.
    - name: get-room
      description: Get detailed information about a specific Matrix room
      hints:
        readOnly: true
        openWorld: false
      call: synapse-admin.get-room
      with:
        roomId: tools.roomId
      outputParameters:
      - type: object
        mapping: $.
    - name: get-room-members
      description: List all members of a specific Matrix room
      hints:
        readOnly: true
        openWorld: false
      call: synapse-admin.get-room-members
      with:
        roomId: tools.roomId
      outputParameters:
      - type: object
        mapping: $.
    - name: create-registration-token
      description: Create a new registration token for controlled user sign-up
      hints:
        readOnly: false
        destructive: false
      call: synapse-admin.create-registration-token
      outputParameters:
      - type: object
        mapping: $.
    - name: list-registration-tokens
      description: List all registration tokens and their usage status
      hints:
        readOnly: true
        openWorld: false
      call: synapse-admin.list-registration-tokens
      outputParameters:
      - type: object
        mapping: $.
    - name: get-server-version
      description: Get the current Synapse homeserver version and Python version
      hints:
        readOnly: true
        openWorld: false
      call: synapse-admin.get-server-version
      outputParameters:
      - type: object
        mapping: $.