US Senate Lobbying Transparency

naftiko: 1.0.0-alpha2
info:
  label: US Senate Lobbying Transparency
  description: Unified capability for lobbying disclosure research and transparency, combining access to LDA filings, registrant
    profiles, client information, and lobbyist records. Supports investigative journalists, researchers, compliance teams,
    and transparency advocates.
  tags:
  - Lobbying
  - Government Transparency
  - Federal Government
  - Open Data
  - Campaign Finance
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    LDA_API_KEY: LDA_API_KEY
capability:
  consumes:
  - type: http
    namespace: senate-lda
    baseUri: https://lda.senate.gov/api/v1
    description: Senate LDA REST API for lobbying disclosure data.
    authentication:
      type: apikey
      key: Authorization
      value: Token {{LDA_API_KEY}}
      placement: header
    resources:
    - name: filings
      path: /filings/
      description: Lobbying disclosure filings
      operations:
      - name: list-filings
        method: GET
        description: List lobbying disclosure filings with filtering
        inputParameters:
        - name: filing_type
          in: query
          type: string
          required: false
          description: Filing type code
        - name: filing_year
          in: query
          type: integer
          required: false
          description: Year of filing
        - name: registrant_name
          in: query
          type: string
          required: false
          description: Registrant name filter
        - name: client_name
          in: query
          type: string
          required: false
          description: Client name filter
        - name: issue_code
          in: query
          type: string
          required: false
          description: Lobbying issue code
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: filing-detail
      path: /filings/{filing_uuid}/
      description: Individual filing record
      operations:
      - name: get-filing
        method: GET
        description: Get a specific filing by UUID
        inputParameters:
        - name: filing_uuid
          in: path
          type: string
          required: true
          description: Filing UUID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: registrants
      path: /registrants/
      description: Lobbying registrants
      operations:
      - name: list-registrants
        method: GET
        description: List lobbying registrants
        inputParameters:
        - name: name
          in: query
          type: string
          required: false
          description: Name filter
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-registrant
        method: GET
        description: Get a specific registrant by ID
        inputParameters:
        - name: id
          in: path
          type: integer
          required: true
          description: Registrant ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: clients
      path: /clients/
      description: Lobbying clients
      operations:
      - name: list-clients
        method: GET
        description: List lobbying clients
        inputParameters:
        - name: name
          in: query
          type: string
          required: false
          description: Name filter
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: lobbyists
      path: /lobbyists/
      description: Individual lobbyists
      operations:
      - name: list-lobbyists
        method: GET
        description: List lobbyists
        inputParameters:
        - name: name
          in: query
          type: string
          required: false
          description: Name filter
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: constants-issues
      path: /constants/filing/lobbyingactivityissues/
      description: Lobbying issue codes
      operations:
      - name: list-lobbying-issues
        method: GET
        description: Get all lobbying activity issue codes
        outputRawFormat: json
        outputParameters:
        - name: result
          type: array
          value: $.
    - name: constants-government
      path: /constants/filing/governmententities/
      description: Government entity codes
      operations:
      - name: list-government-entities
        method: GET
        description: Get all lobbied government entity codes
        outputRawFormat: json
        outputParameters:
        - name: result
          type: array
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: lobbying-transparency-api
    description: Unified REST API for Senate lobbying disclosure research.
    resources:
    - path: /v1/filings
      name: filings
      description: Lobbying disclosure filings
      operations:
      - method: GET
        name: search-filings
        description: Search lobbying disclosure filings
        call: senate-lda.list-filings
        with:
          filing_year: rest.filing_year
          filing_type: rest.filing_type
          issue_code: rest.issue_code
          registrant_name: rest.registrant_name
          client_name: rest.client_name
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/filings/{filing_uuid}
      name: filing
      description: Individual filing detail
      operations:
      - method: GET
        name: get-filing
        description: Get a specific filing by UUID
        call: senate-lda.get-filing
        with:
          filing_uuid: rest.filing_uuid
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/registrants
      name: registrants
      description: Lobbying registrants
      operations:
      - method: GET
        name: search-registrants
        description: Search lobbying registrants
        call: senate-lda.list-registrants
        with:
          name: rest.name
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/clients
      name: clients
      description: Lobbying clients
      operations:
      - method: GET
        name: search-clients
        description: Search lobbying clients
        call: senate-lda.list-clients
        with:
          name: rest.name
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/lobbyists
      name: lobbyists
      description: Individual lobbyists
      operations:
      - method: GET
        name: search-lobbyists
        description: Search individual lobbyists
        call: senate-lda.list-lobbyists
        with:
          name: rest.name
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/reference/issues
      name: issue-codes
      description: Lobbying issue codes
      operations:
      - method: GET
        name: list-issue-codes
        description: Get all lobbying activity issue codes
        call: senate-lda.list-lobbying-issues
        outputParameters:
        - type: array
          mapping: $.
    - path: /v1/reference/government-entities
      name: government-entities
      description: Lobbied government entities
      operations:
      - method: GET
        name: list-government-entities
        description: Get all government entity codes
        call: senate-lda.list-government-entities
        outputParameters:
        - type: array
          mapping: $.
  - type: mcp
    port: 9090
    namespace: lobbying-transparency-mcp
    transport: http
    description: MCP server for AI-assisted lobbying disclosure research.
    tools:
    - name: search-lobbying-filings
      description: Search Senate lobbying disclosure filings (LD-1 registrations, LD-2 quarterly reports). Filter by year,
        period, registrant name, client name, or issue code.
      hints:
        readOnly: true
        openWorld: true
      call: senate-lda.list-filings
      with:
        filing_year: tools.filing_year
        filing_type: tools.filing_type
        issue_code: tools.issue_code
        registrant_name: tools.registrant_name
        client_name: tools.client_name
        page: tools.page
      outputParameters:
      - type: object
        mapping: $.
    - name: get-lobbying-filing
      description: Get complete details of a specific lobbying disclosure filing including activities and lobbyists
      hints:
        readOnly: true
        openWorld: false
      call: senate-lda.get-filing
      with:
        filing_uuid: tools.filing_uuid
      outputParameters:
      - type: object
        mapping: $.
    - name: search-lobbying-registrants
      description: Search registered lobbying firms and individual lobbyists by name
      hints:
        readOnly: true
        openWorld: true
      call: senate-lda.list-registrants
      with:
        name: tools.name
        page: tools.page
      outputParameters:
      - type: object
        mapping: $.
    - name: search-lobbying-clients
      description: Search organizations and entities that have hired lobbyists
      hints:
        readOnly: true
        openWorld: true
      call: senate-lda.list-clients
      with:
        name: tools.name
        page: tools.page
      outputParameters:
      - type: object
        mapping: $.
    - name: search-lobbyists
      description: Search individual registered lobbyists by name
      hints:
        readOnly: true
        openWorld: true
      call: senate-lda.list-lobbyists
      with:
        name: tools.name
        page: tools.page
      outputParameters:
      - type: object
        mapping: $.
    - name: list-lobbying-issue-codes
      description: Get all issue area codes used to categorize lobbying activities (e.g., TAX, HCR, DEF)
      hints:
        readOnly: true
        openWorld: false
      call: senate-lda.list-lobbying-issues
      outputParameters:
      - type: array
        mapping: $.
    - name: list-government-entities
      description: Get all government bodies and agencies that appear as lobbying targets
      hints:
        readOnly: true
        openWorld: false
      call: senate-lda.list-government-entities
      outputParameters:
      - type: array
        mapping: $.