### DADL Setup Object Example

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

Defines human-readable instructions for setting up a DADL backend, including credential steps, environment variable configuration, and example backend YAML.

```yaml
setup:
  credential_steps:
    - "Navigate to GitLab → Settings → Access Tokens"
    - "Create a token with scope: api (full access) or read_api (read-only)"
    - "Copy the token (starts with glpat-)"
  env_var: CREDENTIAL_GITLAB_TOKEN
  backends_yaml: |
    - name: gitlab
      transport: rest
      dadl: /app/dadl/gitlab.dadl
      url: "https://your-gitlab.example.com/api/v4"
  required_scopes:
    - api
  optional_scopes:
    - read_api
  docs_url: "https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html"
  notes: "For self-hosted GitLab, replace the URL with your instance. The token prefix glpat- is for personal access tokens."
```

--------------------------------

### Enable Example Unit Backend

Source: https://github.com/dunkelcloud/toolmesh/blob/main/config/units/README.md

To enable an example unit, copy or symlink the example directory into the active units directory. Restart ToolMesh for the changes to take effect.

```bash
cp -r examples/dice ./dice
```

```bash
ln -s examples/dice ./dice
```

--------------------------------

### Start ToolMesh with Docker Compose

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CLAUDE.md

Copies the example configuration, starts ToolMesh in detached mode, and verifies its health.

```bash
cp .env.example .env
docker compose up -d
curl http://localhost:8123/health
```

--------------------------------

### Backend Object with Coverage and Hints Example

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

This example demonstrates how to define a backend object, including its coverage metadata and hints for LLM integration. The coverage section details the API's scope, while hints provide specific guidance for using tools.

```yaml
backend:
  name: github
  coverage:
    endpoints: 24
    total_endpoints: 900
    percentage: 3
    focus: "repos, issues, PRs, commits, search, releases, actions"
    missing: "git primitives, projects v2, teams, webhooks, code scanning"
    last_reviewed: "2026-03-26"

  hints:
    list_project_tasks:
      position_type: float64
      requires: "call list_views first to get view_id"
      kanban_note: "kanban views return buckets with nested tasks, not a flat list"
```

--------------------------------

### DADL Examples Array for LLM Few-Shot Prompts

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

Provides few-shot code examples for LLMs in Code Mode, demonstrating multi-step workflows using `api.*` calls.

```yaml
examples:
  - name: "Customer onboarding"
    description: "Create a customer and retrieve their details"
    code: |
      const customer = await api.create_customer({
        email: "jane@example.com",
        name: "Jane Doe"
      });
      const details = await api.get_customer({ id: customer.id });
      return details;
```

--------------------------------

### Run ToolMesh Locally with Docker Compose

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CONTRIBUTING.md

Start the ToolMesh services using Docker Compose. This command assumes Docker and Docker Compose v2 are installed and configured.

```bash
docker compose up -d
```

--------------------------------

### Prometheus Query Examples

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/metrics.md

Examples of PromQL queries for analyzing ToolMesh metrics, including login rates, tool call failures, and latency.

```promql
# Login attempts per second by method, last 5 minutes
sum by (method) (rate(toolmesh_logins_total[5m]))
```

```promql
# Failed login ratio
sum(rate(toolmesh_logins_total{result="failure"}[5m]))
  / sum(rate(toolmesh_logins_total[5m]))
```

```promql
# Tool-call error+denied rate per backend
sum by (backend) (rate(toolmesh_tool_calls_total{result=~"error|denied"}[5m]))
  / sum by (backend) (rate(toolmesh_tool_calls_total[5m]))
```

```promql
# Authorization-denied calls per backend, last hour
sum by (backend) (increase(toolmesh_tool_calls_total{result="denied"}[1h]))
```

```promql
# p95 tool-call latency per backend
histogram_quantile(0.95,
  sum by (backend, le) (rate(toolmesh_tool_call_duration_seconds_bucket[5m])))
```

--------------------------------

### Minimal DADL File Example

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

This is a minimal example of a DADL file, demonstrating the required 'spec' field and optional fields like 'credits', 'source_name', 'source_url', 'date', and the 'backend' definition.

```yaml
# minimal.dadl
spec: "https://dadl.ai/spec/dadl-spec-v0.1.md"
credits:                                      # optional
  - "Jane Doe (@janedoe)"
  - "Acme Corp — verifies against production"
source_name: "Example REST API"              # optional
source_url: https://docs.example.com/api     # optional
date: "2026-03-26"                            # optional

backend:
  name: my-api
  type: rest
  version: "1.0"
  base_url: https://api.example.com/v1
  description: "My REST API"

  auth:
    type: bearer
    credential: vault/my-api-token

  tools:
    list_items:
      method: GET
      path: /items
      access: read
      description: "List all items"

```

--------------------------------

### Clone and Set Up ToolMesh Project

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CONTRIBUTING.md

Clone the ToolMesh repository, navigate into the directory, download Go modules, and build the project. Ensure Go 1.25+ and Docker are installed.

```bash
git clone https://github.com/DunkelCloud/ToolMesh.git
cd ToolMesh
go mod download
go build ./...
go test ./...
```

--------------------------------

### Cursor-Based Pagination Configuration

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

Example of configuring cursor-based pagination, specifying request parameters, response cursors, and behavior.

```yaml
pagination:
  strategy: cursor
  request:
    cursor_param: after
    limit_param: per_page
    limit_default: 50
  response:
    next_cursor: "$.meta.next_cursor"
    has_more: "$.meta.has_more"
  behavior: auto              # auto | expose
  max_pages: 10              # safety limit
```

--------------------------------

### Parameter Definition Example

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

Defines path, query, and body parameters for a tool. Note the use of `in: body` for parameters that are part of the request body.

```yaml
# params — path, query, and body parameters in one place
params:
  id:
    type: string
    in: path
    required: true
  limit:
    type: integer
    in: query
    default: 10
    description: "Max items to return"
  name:
    type: string
    in: body
    required: true
    description: "Resource name"
  tags:
    type: array
    in: body
    description: "List of tags"
  metadata:
    type: object
    in: body
    description: "Arbitrary key-value metadata"
```

--------------------------------

### Discover and Execute Tools with ToolMesh

Source: https://github.com/dunkelcloud/toolmesh/blob/main/README.md

Use `discover_tools` and `execute_code` meta-tools to interact with multiple MCP servers efficiently. This example demonstrates fetching GitHub repositories and then listing open issues for the first repository.

```javascript
const repos = await toolmesh.github_list_repos({ sort: "updated" });
const issues = await toolmesh.github_list_issues({
  owner: repos[0].owner.login,
  repo: repos[0].name,
  state: "open"
});
```

--------------------------------

### Register a REST Backend with DADL

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CLAUDE.md

Copies the example backend configuration and adds a new backend entry specifying its name, transport type, DADL file, and URL.

```yaml
backends:
  - name: deepl
    transport: rest
    dadl: deepl.dadl
    url: "https://api.deepl.com/v2"
```

--------------------------------

### DADL Backend Version Example

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

Specifies an optional semantic version string for a DADL file, enabling ToolMesh to check for registry updates.

```yaml
backend:
  name: github
  version: "1.2"
  # ...
```

--------------------------------

### Useful ToolMesh Commands

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CLAUDE.md

Provides essential commands for managing ToolMesh, including starting, viewing logs, restarting, and health checking.

```bash
docker compose up -d              # Start ToolMesh
docker compose logs -f toolmesh   # View logs
docker compose restart toolmesh   # Restart after config changes
curl http://localhost:8123/health  # Health check
```

--------------------------------

### Configure External MCP Server

Source: https://github.com/dunkelcloud/toolmesh/blob/main/README.md

Example configuration for adding an external MCP server to ToolMesh. Ensure the API key is set as an environment variable.

```yaml
backends:
  - name: memorizer
    transport: http
    url: "https://memorizer.example.com/mcp"
    api_key_env: "MEMORIZER_API_KEY"
```

--------------------------------

### Prometheus Scrape Configuration

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/metrics.md

Example YAML configuration for Prometheus to scrape ToolMesh metrics from the default endpoint.

```yaml
scrape_configs:
  - job_name: toolmesh
    scrape_interval: 30s
    static_configs:
      - targets: ['toolmesh.internal:9090']
```

--------------------------------

### Describe Tool Parameters

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CHANGELOG.md

Use `toolmesh.describe` to get the full parameter schema for a specific tool within the sandbox environment. This runs locally and does not count towards the tool-call budget.

```typescript
toolmesh.describe("<tool_name>")
```

--------------------------------

### Define a Composite Tool

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

Example of defining a composite tool named 'get_named_status' which retrieves device status and associates names. It includes an optional parameter 'only_on' to filter results.

```yaml
composites:
  get_named_status:
    description: "Get all device status with human-readable names and on/off state"
    params:
      only_on:
        type: boolean
        default: false
        description: "If true, return only devices that are currently on"
    timeout: 30s
    code: |
      const devices = await api.list_devices();
      const nameMap = Object.fromEntries(devices.map(d => [d.id, d.name]));
      const status = await api.get_all_device_status({ show_info: true });
      const result = status.map(d => ({
        ...d,
        name: nameMap[d.id] || d.id
      }));
      if (params.only_on) {
        return result.filter(d => d.relay_on || d.light_on || d.switch_on);
      }
      return result;
```

--------------------------------

### Set MCP API Key Environment Variable

Source: https://github.com/dunkelcloud/toolmesh/blob/main/README.md

Example command to set the API key for an external MCP server as an environment variable. This is required for ToolMesh to authenticate with the external service.

```bash
CREDENTIAL_MEMORIZER_API_KEY=sk-mem-xxxxx
```

--------------------------------

### Minimal DADL File Structure

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CLAUDE.md

Defines the basic structure of a DADL file, including specification, credits, source information, backend details, authentication method, and an example tool definition.

```yaml
spec: "https://dadl.ai/spec/dadl-spec-v0.1.md"
credits:
  - "Your Name"
source_name: "My API"
source_url: "https://api.example.com/docs"
date: "2026-01-01"

backend:
  name: myapi
  type: rest
  base_url: https://api.example.com
  description: "Short description of the API"

  auth:
    type: bearer
    credential: myapi_token
    inject_into: header
    header_name: Authorization
    prefix: "Bearer "

  tools:
    list_items:
      method: GET
      path: /items
      description: "List all items"
      params:
        limit:
          type: integer
          in: query
          description: "Max items to return"
```

--------------------------------

### Build and Push Docker Image for Development

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CONTRIBUTING.md

Builds and pushes a Docker image tagged as ':dev' for local development and testing against the dev environment.

```bash
make docker-dev
```

--------------------------------

### DADL vs. Traditional API Integration

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

Illustrates the simplified integration flow with DADL compared to traditional methods requiring custom MCP servers.

```text
# Without DADL
Claude → ToolMesh → custom Go/TS MCP Server → REST API

# With DADL
Claude → ToolMesh → REST API  (via declarative .dadl file)
```

--------------------------------

### Architecture Comparison: Current vs. DADL

Source: https://github.com/dunkelcloud/toolmesh/blob/main/README.md

Illustrates the architectural shift when using DADL files to directly connect AI agents to REST APIs via ToolMesh, bypassing traditional MCP server wrappers.

```text
Current:    Claude → ToolMesh → MCP Server → REST API
With DADL:  Claude → ToolMesh → REST API (via .dadl file)
```

--------------------------------

### Sandbox Security: Clearing Constructor Reference

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CHANGELOG.md

The `LockdownRuntime` clears the `constructor` reference on intrinsic prototypes before installing `eval`/`Function` stubs to prevent prototype-chain access to the Function constructor.

```go
runtime.LockdownRuntime().Clear("constructor")
```

--------------------------------

### Clone and Configure ToolMesh

Source: https://github.com/dunkelcloud/toolmesh/blob/main/README.md

Clone the ToolMesh repository and set up the necessary environment variables for authentication. This includes setting a password or an API key for secure access.

```bash
# Clone
git clone https://github.com/DunkelCloud/ToolMesh.git
cd ToolMesh

# Configure
cp .env.example .env
# IMPORTANT: Set a password — without it, all requests are rejected:
#   TOOLMESH_AUTH_PASSWORD=my-secret-password
# Or set an API key for programmatic access:
#   TOOLMESH_API_KEY=my-api-key

# Optional: local overrides (build locally, enable OpenFGA, HTTPS proxy, ...)
# cp docker-compose.override.yml.example docker-compose.override.yml
# # then edit docker-compose.override.yml — picked up automatically by Docker Compose

# Start (runs in bypass mode by default — no authz required)
docker compose up -d

# Verify it's running (default port: 8123)
curl http://localhost:8123/health

# MCP endpoint: http://localhost:8123/mcp
# Note: Most MCP clients require HTTPS — see TLS section below
```

--------------------------------

### Configure Bundled DADL

Source: https://github.com/dunkelcloud/toolmesh/blob/main/dadl/README.md

Add an entry to `config/backends.yaml` to enable a bundled DADL like `hackernews.dadl`. Restart ToolMesh after configuration.

```yaml
backends:
  - name: hackernews
    transport: rest
    dadl: hackernews.dadl
```

--------------------------------

### Configure Claude Desktop MCP Server (HTTP for Local Development)

Source: https://github.com/dunkelcloud/toolmesh/blob/main/README.md

Add the ToolMesh MCP server configuration to Claude Desktop for local development, using an HTTP URL. This bypasses TLS and is suitable for local testing.

```json
{
  "mcpServers": {
    "toolmesh": {
      "url": "http://localhost:8123/mcp"
    }
  }
}
```

--------------------------------

### Discover Tools with Free-Text Search

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CHANGELOG.md

Use `toolmesh.discover` for in-sandbox discovery of tools based on free-text queries. It returns ranked matches including name, description, and backend.

```typescript
toolmesh.discover("<free text>", limit?)
```

--------------------------------

### create_customer

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

Create a new customer with the provided details.

```APIDOC
## POST /customers

### Description
Create a new customer with the provided details.

### Method
POST

### Endpoint
/customers

### Parameters
#### Request Body
- **email** (string) - Required - The customer's email address.
- **name** (string) - Optional - The customer's name.
- **metadata** (object) - Optional - Key-value pairs to store additional information.

### Request Example
{
  "email": "jane@example.com",
  "name": "Jane Doe"
}

### Response
#### Success Response (200)
- **id** (string) - The newly created customer's unique identifier.
- **email** (string) - The customer's email address.

#### Response Example
{
  "id": "cus_456",
  "email": "jane@example.com"
}
```

--------------------------------

### Configure REST Backend

Source: https://github.com/dunkelcloud/toolmesh/blob/main/README.md

Add a REST backend to `config/backends.yaml` to enable direct REST API calls.

```yaml
backends:
  - name: vikunja
    transport: rest
    dadl: /app/dadl/vikunja.dadl
    url: "https://vikunja.example.com/api/v1"
```

--------------------------------

### Build Enterprise Extensions

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/architecture.md

Include enterprise extensions in your build by specifying the 'enterprise' tag.

```bash
go build -tags enterprise ./cmd/toolmesh
```

--------------------------------

### Basic Authentication Configuration

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

Set up basic authentication using username and password credentials. ToolMesh automatically constructs the Authorization header. Supports APIs that use API keys as usernames.

```yaml
# auth — basic
auth:
  type: basic
  username_credential: vault/bitdefender-api-key
  password_credential: vault/bitdefender-password  # optional, default: ""
```

--------------------------------

### Set Backend Credentials

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CLAUDE.md

Adds the necessary credential to the .env file for a backend, following the naming convention: CREDENTIAL_ + DADL's credential field in UPPER_SNAKE_CASE.

```bash
CREDENTIAL_DEEPL_AUTH_KEY=your-deepl-api-key
```

--------------------------------

### File Response Handling

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CHANGELOG.md

Tools declaring `response: {type: file_url, ttl: ...}` store binary responses in the file broker and return a download URL. This avoids inlining raw bytes as text and respects a per-tool TTL.

```dadl
response: {type: file_url, ttl: ...}
```

--------------------------------

### Define Binary and Streaming Responses

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

Configure tools to return binary files like PDFs or stream real-time events. Specify content types for binary responses and handling strategies for streams.

```yaml
download_report:
  method: GET
  path: /reports/{id}/pdf
  description: "Download report as PDF"
  response:
    binary: true
    content_type: application/pdf

event_stream:
  method: GET
  path: /events
  description: "Stream real-time events"
  response:
    streaming: true
    stream_handling: collect    # collect | skip
    max_duration: 30s
    max_items: 100
```

--------------------------------

### Configure ToolMesh Authentication

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CLAUDE.md

Sets up authentication for ToolMesh using either an API key for scripts or a password for browser-based clients.

```bash
# Option A: API key (for Claude Code, scripts)
TOOLMESH_API_KEY=my-api-key

# Option B: Password (for Claude Desktop, browser-based clients)
TOOLMESH_AUTH_PASSWORD=my-password
```

--------------------------------

### Binary Response to File URL

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

Configures a tool to return binary data as a file URL. The `response.type` is set to `file_url`, and a `ttl` can be specified for the download link.

```yaml
# binary response → file URL
export_report:
  method: GET
  path: /reports/{id}/export
  description: "Export report as PDF"
  params:
    id: { type: string, in: path, required: true }
  response:
    type: file_url
    ttl: 24h
```

--------------------------------

### Configure ToolMesh MCP Server for Claude Desktop

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CLAUDE.md

Adds a ToolMesh MCP server configuration for Claude Desktop. Note that Claude Desktop requires HTTPS.

```json
{
  "mcpServers": {
    "toolmesh": {
      "url": "https://toolmesh.example.com/mcp"
    }
  }
}
```

--------------------------------

### ToolMesh Execution Pipeline Sequence Diagram

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/architecture.md

Visualizes the sequence of operations during tool execution within the ToolMesh system, showing interactions between the AI Agent, MCP Server, Executor, OpenFGA, Credential Store, Backend, and Output Gate.

```mermaid
sequenceDiagram
    participant Agent as AI Agent
    participant MCP as MCP Server
    participant Exec as Executor
    participant FGA as OpenFGA
    participant Cred as Credential Store
    participant Back as Backend (MCP Client)
    participant Gate as Output Gate

    Agent->>MCP: tools/call
    MCP->>Exec: ExecuteTool()
    Exec->>FGA: Check(user, can_execute, tool)
    FGA-->>Exec: allowed/denied
    alt denied
        Exec-->>MCP: Error: unauthorized
    end
    Exec->>Cred: Get(api_key, tenant)
    Cred-->>Exec: credential
    Exec->>Back: Execute(tool, params)
    Back-->>Exec: ToolResult
    Exec->>Gate: Evaluate(context)
    Gate-->>Exec: pass/reject
    Exec-->>MCP: ToolResult
    MCP-->>Agent: response
```

--------------------------------

### Generate Bcrypt Password Hash

Source: https://github.com/dunkelcloud/toolmesh/blob/main/README.md

Use any bcrypt-compatible utility to generate password hashes for user authentication. This command generates a hash for a given password.

```bash
htpasswd -nbBC 10 "" "my-password" | cut -d: -f2
```

--------------------------------

### Configure Internal REST Backend

Source: https://github.com/dunkelcloud/toolmesh/blob/main/README.md

Configure a REST backend for internal services, allowing private IPs and skipping TLS verification for self-signed certificates.

```yaml
backends:
  - name: internal-api
    transport: rest
    dadl: internal.dadl
    url: "https://192.168.1.50:8443/api"
    allow_private_url: true    # allow private/loopback addresses (default: true)
    tls_skip_verify: true      # accept self-signed certificates (default: false)
```

--------------------------------

### Define API Keys for Programmatic Access

Source: https://github.com/dunkelcloud/toolmesh/blob/main/README.md

Configure API keys with bcrypt-hashed keys in `config/apikeys.yaml`. Each key maps to a distinct user identity for programmatic access.

```yaml
keys:
  - key_hash: "$2a$10$..."
    user_id: claude-code-user
    company_id: dunkelcloud
    plan: pro
    roles: [tool-executor]
```

--------------------------------

### Set Credential Environment Variables

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/configuration.md

Set environment variables with the `CREDENTIAL_` prefix to store sensitive credential values. Use a logical name for each credential.

```bash
CREDENTIAL_MEMORIZER_API_KEY=sk-mem-xxxxx
CREDENTIAL_BRAVE_API_KEY=BSA-xxxxx
```

--------------------------------

### ToolMesh Project Structure

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/architecture.md

Illustrates the directory layout of the ToolMesh project, highlighting the organization of source code, configuration, tools, and documentation.

```tree
toolmesh/
├── cmd/
│   ├── toolmesh/       # Main entrypoint (MCP Server)
│   └── lint-dadl/      # CLI: Validate DADL composite files
├── internal/
│   ├── mcp/            # MCP Server (Streamable HTTP + STDIO)
│   ├── backend/        # ToolBackend interface + MCPAdapter
│   ├── executor/       # ExecuteTool pipeline (AuthZ → Creds → Gate → Exec → Audit)
│   ├── audit/          # Audit store interface + log/sqlite implementations
│   ├── authz/          # OpenFGA authorization
│   ├── credentials/    # Credential store interface + EmbeddedStore
│   ├── gate/           # Output Gate (goja policy engine)
│   ├── userctx/        # UserContext propagation
│   └── config/         # Environment-based configuration
├── config/             # Backend configuration (backends.yaml)
├── tools/              # TypeScript tool definitions (canonical source)
└── docs/               # Documentation
```

--------------------------------

### Enable Per-Backend Debug Logging

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/configuration.md

Set DEBUG_BACKENDS and DEBUG_FILE to enable debug-level logging for specific backends to a separate file. This is useful for troubleshooting individual backend issues without cluttering the main log. Ensure LOG_LEVEL is set appropriately for stdout logging.

```bash
DEBUG_BACKENDS=github
DEBUG_FILE=debug.log
LOG_LEVEL=error
```

--------------------------------

### Define Tool for Listing GitHub Issues

Source: https://github.com/dunkelcloud/toolmesh/blob/main/README.md

Define a tool in YAML format for an LLM to list GitHub issues, specifying the HTTP method, path, and parameters.

```yaml
tools:
  list_issues:
    method: GET
    path: /repos/{owner}/{repo}/issues
    description: "List issues for a repository"
    params:
      owner: { type: string, in: path, required: true }
      repo:  { type: string, in: path, required: true }
      state: { type: string, in: query }
```

--------------------------------

### Sandbox Memory Limits

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CHANGELOG.md

Goja runtimes are subject to a soft heap limit via `TOOLMESH_MEM_LIMIT_BYTES` or `GOMEMLIMIT`, and a per-runtime call-stack cap. `docker-compose.yml` also sets `mem_limit` and `restart`.

```shell
TOOLMESH_MEM_LIMIT_BYTES=1GB
```

```shell
GOMEMLIMIT=1GB
```

--------------------------------

### OpenFGA Authorization Model

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/architecture.md

Defines a relationship-based model for fine-grained authorization in ToolMesh. Authorization checks occur before tool execution, ensuring requests are permitted based on defined relationships.

```plaintext
user → subscribes to → plan → associated with → tool
```

--------------------------------

### JavaScript for Tool Execution

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/architecture.md

LLMs can write typed JavaScript for tool calls, enabling more robust interactions with enterprise infrastructure. The `execute_code` tool accepts JavaScript and runs it in a sandboxed environment.

```javascript
toolmesh.discover()
toolmesh.describe()
```

--------------------------------

### Ignoring Publisher Credential Files

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CHANGELOG.md

Publisher credential files (e.g., `.mcpregistry_*`) are now git-ignored. A `gitleaks` job is also run in CI to scan for secrets.

```git
echo ".mcpregistry_*" >> .gitignore
```

--------------------------------

### Define Users for OAuth 2.1 Authentication

Source: https://github.com/dunkelcloud/toolmesh/blob/main/README.md

Configure users with bcrypt-hashed passwords in `config/users.yaml`. This method is for interactive login.

```yaml
users:
  - username: admin
    password_hash: "$2a$10$..."
    company: dunkelcloud
    plan: pro
    roles: [admin]
```

--------------------------------

### ToolMesh Architecture Diagram

Source: https://github.com/dunkelcloud/toolmesh/blob/main/README.md

Visual representation of the ToolMesh architecture, showing its core components and external integrations.

```text
                          ┌─────────────────────────────────┐
                          │          ToolMesh               │
                          │                                 │
                          │  Redis · OpenFGA · Audit        │
                          │  Credential Store · JS Gate     │
                          │                                 │
AI Agent ──MCP──────────▶ │   AuthZ ▸ Creds ▸ Gate ▸ Exec  │
                          │                                 │
                          └──┬──────┬───────┬───────┬───────┘
                             │      │       │       │
                          MCP Client  .dadl   .dadl   .dadl
                             │      │       │       │
                             ▼      ▼       ▼       ▼
                          MCP     Stripe  GitHub  Vikunja
                          Server   API     API     API
```

--------------------------------

### Static Scanner: Flagging Blocklisted Properties

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CHANGELOG.md

The `ScanCode` static scanner now flags blocklisted property names in both dot (`obj.constructor`) and string-literal bracket (`obj["constructor"]`) access forms.

```go
ScanCode.Flag("blocklisted_property_name")
```

--------------------------------

### OAuth 2.0 Client Credentials Configuration

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

Configure OAuth 2.0 client credentials flow for obtaining tokens. Specify token URL, client credentials, scopes, and caching options.

```yaml
# auth — oauth2
auth:
  type: oauth2
  flow: client_credentials
  token_url: https://api.example.com/oauth/token
  client_id_credential: vault/example-client-id
  client_secret_credential: vault/example-client-secret
  scopes: ["read", "write"]
  token_cache_key: example-api-token
  refresh_before_expiry: 60s
```

--------------------------------

### Enable Debug Tools

Source: https://github.com/dunkelcloud/toolmesh/blob/main/README.md

Set `TOOLMESH_DEBUG_TOOLS` to `true` to enable diagnostic MCP tools for development and incident triage. These tools are off by default.

```bash
TOOLMESH_DEBUG_TOOLS=true
```

--------------------------------

### File URL Fetching Security Option

Source: https://github.com/dunkelcloud/toolmesh/blob/main/CHANGELOG.md

Caller-supplied `file_url` fetches are now governed by `allow_private_file_url` (default `false`) and `file_url_allowed_hosts`. This prevents SSRF to internal endpoints from the default configuration.

```shell
allow_private_file_url: false
```

```shell
file_url_allowed_hosts: ["example.com"]
```

--------------------------------

### API Key Authentication Configuration

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

Configure API key authentication for requests. Specify the credential and where to inject the key (header or query parameter).

```yaml
# auth — api_key
auth:
  type: api_key
  credential: vault/my-api-key
  inject_into: header          # header | query
  header_name: X-API-Key
```

--------------------------------

### get_customer

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

Retrieve a single customer by ID.

```APIDOC
## GET /customers/{id}

### Description
Retrieve a single customer by ID.

### Method
GET

### Endpoint
/customers/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the customer.

### Response
#### Success Response (200)
- **id** (string) - The customer's unique identifier.
- **email** (string) - The customer's email address.

#### Response Example
{
  "id": "cus_123",
  "email": "jane@example.com"
}
```

--------------------------------

### list_customers

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

List all customers. Supports filtering by email and limiting the number of results.

```APIDOC
## GET /customers

### Description
List all customers. Supports filtering by email and limiting the number of results.

### Method
GET

### Endpoint
/customers

### Parameters
#### Query Parameters
- **email** (string) - Optional - Filter customers by email address.
- **limit** (integer) - Optional - The maximum number of customers to return. Defaults to 10.

### Response
#### Success Response (200)
- **data** (array) - A list of customer objects.
- **has_more** (boolean) - Indicates if there are more results available.

#### Response Example
{
  "data": [
    {
      "id": "cus_123",
      "email": "jane@example.com"
    }
  ],
  "has_more": true
}
```

--------------------------------

### Default Response Transformation Configuration

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

Applies a default JSONPath for the result, a separate path for metadata, and a jq filter for transformation to all tools unless overridden. Sets a maximum number of items and allows LLM-driven jq overrides.

```yaml
# defaults.response — applies to all tools unless overridden
response:
  result_path: "$.data"             # JSONPath to the actual result
  metadata_path: "$.meta"           # extracted separately (for pagination, not sent to LLM)
  transform: |                      # optional jq filter
    .data | map({id, name, status})
  max_items: 100
  allow_jq_override: true           # LLM can pass ad-hoc jq filters

```

--------------------------------

### YAML Anchors for Intra-file Reuse

Source: https://github.com/dunkelcloud/toolmesh/blob/main/docs/dadl-spec-v0.1.md

Utilize YAML anchors for defining reusable blocks within the same file. Underscore-prefixed keys are ignored by ToolMesh.

```yaml
# YAML anchors — native DRY
# Underscore-prefixed keys are ignored by ToolMesh
_defaults:
  pagination: &default-pagination
    strategy: cursor
    request:
      limit_param: limit
      limit_default: 50
    behavior: auto
    max_pages: 20

backend:
  defaults:
    pagination:
      <<: *default-pagination
      request:
        cursor_param: starting_after
```