@xano/developer-mcp 1.0.0

package/xanoscript_docs/tips_and_tricks.md

@@ -0,0 +1,144 @@
+---
+applyTo: "**/*.xs"
+---
+
+# Tips and Tricks
+
+## Variable definition
+
+Xano doesn't have a concept of variable scope, you can define a variable anywhere in the stack and use it anywhere else.
+
+```xs
+var $greeting {
+  value = "Hello, World!"
+}
+```
+
+if defining an object or array, use `{}` or `[]`:
+
+```xs
+var $user {
+  value = {
+    name: "John Doe"
+    email: "john.doe@example.com"
+  }
+}
+```
+
+```xs
+var $numbers {
+  value = [1, 2, 3, 4, 5]
+}
+```
+
+## External API requests
+
+When making an external API request, you'll want to use `params` for the request body, there is `body` keyword
+
+## Comments
+
+Use description argument on the statement or a comment `//` above it. Do not use description on responses, they do not support it. A comment can only be placed above a statement, not inside it.
+
+````xs
+// A simple hello world function
+function "hello_world" {
+  input {
+    // The name of the person to greet
+    text name
+  }
+
+  stack {
+    // A simple greeting message
+    var $greeting {
+      value = "Hello, World!"
+    }
+  }
+
+  response = $greeting
+}
+
+## Environment Variables
+
+Always assume secrets and other configuration values are stored in the $env.<variable_name>, it's the responsibility of the user to create the values. Do not create a `.env` file. When adding a new environment variable, make sure to document it clearly and provide instructions for how to set it up.
+
+## Conditionals
+
+Conditionals accepts only one `if` and one `else` but you can add many `elseif` blocks.
+
+## Existing logic and data schema
+
+Try to reuse existing logic and data schema whenever possible. This includes using existing functions, API groups, data models, and API endpoints to avoid duplication and ensure consistency across your application.
+
+## Large text
+
+When dealing with large body of text (like a webpage, email body, AI prompt) it's best practice to use the `util.template_engine` function to manage and format the text efficiently. This templating system uses TWIG syntax.
+
+```xs
+    util.template_engine {
+      description = "Create HTML table from event data"
+      value = """
+        <table>
+          <thead>
+            <tr>
+              <th>ID</th>
+              <th>Created At</th>
+              <th>Type</th>
+              <th>User ID</th>
+              <th>Metadata</th>
+              <th>Source</th>
+              <th>IP Address</th>
+            </tr>
+          </thead>
+          <tbody>
+            {% for event in events %}
+            <tr>
+              <td>{{ event.id }}</td>
+              <td>{{ event.created_at|format_timestamp("Y-m-d H:i:s", "UTC") }}</td>
+              <td>{{ event.type }}</td>
+              <td>{{ event.user_id ? event.user_id : "-" }}</td>
+              <td>{{ event.metadata ? event.metadata : "-" }}</td>
+              <td>{{ event.source ? event.source : "-" }}</td>
+              <td>{{ event.ip_address ? event.ip_address : "-" }}</td>
+            </tr>
+            {% endfor %}
+          </tbody>
+        </table>
+        """
+    } as $html_table
+````
+
+## Filters
+
+Xanoscript filters on inputs and values are inspired by TWIG, they use `|` to separate the variable from the filter. For example on an input block:
+
+```xs
+input {
+  text filters=trim|lower {
+    description = "Filters to apply to the text input"
+  }
+}
+```
+
+or a variable:
+
+```xs
+var $formatted_date {
+  value = $event.created_at|format_timestamp("Y-m-d H:i:s", "UTC")
+}
+```
+
+or a schema:
+
+```xs
+table "event" {
+  schema {
+    int id
+    timestamp created_at?=now
+    text type filters=trim|lower
+    int user_id? filters=min:0
+    text metadata? filters=trim
+    text source? filters=trim|lower
+    text ip_address? filters=trim
+  }
+}
+```

package/xanoscript_docs/tool_examples.md

@@ -0,0 +1,69 @@
+---
+applyTo: "tools/**/*.xs"
+---
+
+# Xanoscript AI Tool Examples
+
+Below are some examples of AI Tool configurations that can be made using Xanoscript.
+
+## Tool with API, Task, and Tool Calls
+
+This example demonstrates a tool that utilizes all three tool-specific statements: `api.call`, `task.call`, and `tool.call`.
+
+```xs
+tool "new_statements" {
+  description = "A tool that demonstrates calling other Xano resources."
+
+  instructions = "This tool is used to test the functionality of calling APIs, tasks, and other tools from within a tool. It takes a user's name as input and returns the result of an API call."
+
+  input {
+    text name? filters=trim {
+      description = "The name of the user to be used in the various calls. Descriptions are important as they are sent to the AI."
+    }
+  }
+
+  stack {
+    api.call "auth/login" verb=POST {
+      api_group = "Authentication"
+      input = {email: "email@email.com", password: "password"}
+    } as $endpoint1
+
+    task.call "task_example" as $test1
+
+    tool.call "what_is_xano" {
+      input = {query: "What is Xano?"}
+    } as $tool1
+  }
+
+  response = $endpoint1
+
+  history = "inherit"
+}
+```
+
+## Simple Information Retrieval Tool
+
+This is an example of a simple tool that retrieves information.
+
+```xs
+tool "what_is_xano" {
+  description = "Provides a brief description of Xano."
+  instructions = "Use this tool to get a basic explanation of what Xano is."
+
+  input {
+    text query? {
+      description = "A question about Xano. The content of the query is ignored, the tool always returns the same text."
+    }
+  }
+
+  stack {
+    var $xano_description {
+      value = "Xano is a no-code backend platform that allows you to build scalable, secure, and compliant backends without writing any code."
+    }
+  }
+
+  response = $xano_description
+
+  history = 100
+}
+```

package/xanoscript_docs/tool_guideline.md

@@ -0,0 +1,139 @@
+---
+applyTo: "tools/**/*.xs"
+---
+
+# How to Define AI Tools in XanoScript
+
+AI Tools in Xano are specialized, reusable function stacks designed to be executed by [AI Agents](./agent_guideline.md) or exposed externally through an [MCP server](./mcp_server_guideline.md), also known as Model Context Protocol Server. They act as the bridge between an AI's reasoning capabilities and your application's backend, allowing agents to query databases, call APIs, and perform complex actions.
+
+Tools are defined in `<tool_name>.xs` files within the `tools/` directory of your project, they follow the same syntax as standard Xano [function stacks](./function_guideline.md) with some additional features tailored for AI interactions.
+
+For example, you might have a file named `tools/user_lookup.xs` that contains the definition of a tool for looking up user information:
+
+````xs
+tool "user_lookup" {
+  description = "Looks up user information by user ID."
+  instructions = "Use this tool to retrieve detailed information about a user given their unique user ID. Provide the user ID as input, and the tool will return the user's profile data."
+  input {
+    int user_id {
+      description = "The unique identifier of the user to look up."
+    }
+  }
+  stack {
+    db.get "user" {
+      field_name = "id"
+      field_value = $input.user_id
+      description = "Verify user exists"
+    } as $user
+  }
+
+  response = $user
+}
+
+## Core Tool Syntax
+
+Every tool is defined within a `tool` block.
+
+```xs
+tool "unique_tool_name" {
+  description = "A brief explanation of what this tool does."
+  instructions = "Guidelines explaining how AI agents should use this tool, including use cases, input formatting, and output interpretation."
+  input {
+
+  }
+  stack {
+
+  }
+  response = null
+  history = false
+}
+````
+
+### Key Fields
+
+- **`tool "name"`**: The top-level declaration. The name must be a unique string identifier, as this is how the tool is referenced by Agents and MCP servers.
+- **`description`**: An optional string for internal documentation. This is not visible to the AI.
+- **`instructions`**: A required string that provides the AI with the context it needs to use the tool effectively. This is a crucial field for ensuring the tool is used correctly by the agent.
+- **`input`**: An object defining the parameters the tool accepts.
+- **`stack`**: An object containing the sequence of operations to be executed.
+- **`response`**: An object that specifies the data returned by the tool.
+
+---
+
+## Input Block
+
+The `input` block defines the parameters that the tool can accept at runtime. The structure is identical to inputs in other Xano function stacks, but the `description` for each parameter is especially important, as it is included in the information sent to the AI.
+
+### Input Structure
+
+The `input` block accepts a series of field definitions, follow the [input guidleine](./input_guideline.md) for more details
+
+## Stack Block and Tool-Specific Statements
+
+The `stack` contains the tool's logic. In addition to all standard Xano function statements, tools have access to three unique statements for calling other Xano resources.
+
+### 1. `api.call`
+
+Executes an API endpoint from one of your API groups. This is the preferred way to interact with your backend from a tool, as it ensures that all business logic encapsulated in the API is respected.
+
+```xs
+stack {
+  api.call "auth/login" verb=POST {
+    api_group = "Authentication"
+    input = {
+      email: "user@example.com",
+      password: "password123"
+    }
+  } as $login_response
+}
+```
+
+### 2. `task.call`
+
+Executes a background task. Tasks do not accept inputs or return outputs directly.
+
+```xs
+stack {
+  task.call "my_background_task" as $task_call_result
+}
+```
+
+### 3. `tool.call`
+
+```xs
+stack {
+  tool.call "get_user_details" {
+    input = {user_id: 123}
+  } as $user_details
+}
+```
+
+Executes another AI Tool. This allows you to create modular, reusable tools that can be composed together.
+
+- **Syntax**: `tool.call <tool_name> { ... }`
+
+```xs
+stack {
+  tool.call "get_user_details" {
+    input = {user_id: 123}
+  } as $user_details
+}
+```
+
+## Response Block
+
+The `response` block specifies the data that the tool returns to the agent or client that called it. The structure is the same as in other Xano function stacks.
+
+**Example:**
+
+```xs
+response = $user_details
+```
+
+## Best Practices
+
+- **Write Clear Instructions**: The `instructions` field is the most important part of your tool's definition. Be explicit about what the tool does, what each input parameter is for, and what the output means.
+- **Use Descriptive Input Fields**: Clearly describe each input parameter. This information is passed to the AI and helps it construct valid requests.
+- **Leverage Enums**: For inputs with a fixed set of possible values, use an `enum` type. This provides the AI with the exact options it can use, reducing errors.
+- **Keep Tools Focused**: Design tools that perform a single, well-defined task. This makes them easier for the AI to understand and combine.
+- **Handle Errors Gracefully**: Use `filters` on input, `precondition` and `try_catch` blocks in the stack to validate inputs and handle potential errors. Return clear error messages in the response so the AI can understand what went wrong.

package/xanoscript_docs/unit_testing_guideline.md

@@ -0,0 +1,328 @@
+---
+applyTo: "functions/**/*.xs,apis/**/*.xs"
+---
+
+# Unit Testing in XanoScript
+
+Unit tests in XanoScript are defined using the `test` block inside a `function` or `query`. Each test can use various `expect` methods to assert the correctness of your code. Below are examples for all supported `expect` methods.
+
+## Argument-based expects
+
+These expects require a payload block with a `value` or other parameters.
+
+### `expect.to_equal`
+
+```xs
+test "should match email" {
+  expect.to_equal ($response.user.email) {
+    value = "john@example.com"
+  }
+}
+```
+
+Checks that `$response.user.email` equals `"john@example.com"`.
+
+### `expect.to_not_equal`
+
+```xs
+test "should not be error status" {
+  expect.to_not_equal ($response.status) {
+    value = "error"
+  }
+}
+```
+
+Checks that `$response.status` is not `"error"`.
+
+### `expect.to_start_with`
+
+```xs
+test "should start with John" {
+  expect.to_start_with ($response.user.name) {
+    value = "John"
+  }
+}
+```
+
+Checks that `$response.user.name` starts with `"John"`.
+
+### `expect.to_end_with`
+
+```xs
+test "should end with .pdf" {
+  expect.to_end_with ($response.file.name) {
+    value = ".pdf"
+  }
+}
+```
+
+Checks that `$response.file.name` ends with `".pdf"`.
+
+### `expect.to_be_greater_than`
+
+```xs
+test "should be greater than 100" {
+  expect.to_be_greater_than ($response.order.total) {
+    value = 100
+  }
+}
+```
+
+Checks that `$response.order.total` is greater than `100`.
+
+### `expect.to_be_less_than`
+
+```xs
+test "should be less than 10" {
+  expect.to_be_less_than ($response.product.stock_quantity) {
+    value = 10
+  }
+}
+```
+
+Checks that `$response.product.stock_quantity` is less than `10`.
+
+### `expect.to_match`
+
+```xs
+test "should match US phone pattern" {
+  expect.to_match ($response.user.phone) {
+    value = "^\\+1\\d{10}$"
+  }
+}
+```
+
+Checks that `$response.user.phone` matches the regex pattern for a US phone number.
+
+### `expect.to_contain`
+
+```xs
+test "should contain featured tag" {
+  expect.to_contain ($response.tags) {
+    value = "featured"
+  }
+}
+```
+
+Checks that `"featured"` is present in `$response.tags` array.
+
+## Range expects
+
+### `expect.to_be_within`
+
+```xs
+test "should be within range" {
+  expect.to_be_within ($response.temperature) {
+    min = 20
+    max = 30
+  }
+}
+```
+
+Checks that `$response.temperature` is between `20` and `30` (inclusive).
+
+## Argument-less expects
+
+These expects do not require a payload block.
+
+### `expect.to_be_true`
+
+```xs
+test "should be true" {
+  expect.to_be_true ($response.is_active)
+}
+```
+
+Checks that `$response.is_active` is `true`.
+
+### `expect.to_be_false`
+
+```xs
+test "should be false" {
+  expect.to_be_false ($response.is_deleted)
+}
+```
+
+Checks that `$response.is_deleted` is `false`.
+
+### `expect.to_be_in_the_past`
+
+```xs
+test "should be in the past" {
+  expect.to_be_in_the_past ($response.created_at)
+}
+```
+
+Checks that `$response.created_at` is a timestamp in the past.
+
+### `expect.to_be_in_the_future`
+
+```xs
+test "should be in the future" {
+  expect.to_be_in_the_future ($response.scheduled_at)
+}
+```
+
+Checks that `$response.scheduled_at` is a timestamp in the future.
+
+### `expect.to_be_defined`
+
+```xs
+test "should be defined" {
+  expect.to_be_defined ($response.user_id)
+}
+```
+
+Checks that `$response.user_id` is defined.
+
+### `expect.to_not_be_defined`
+
+```xs
+test "should not be defined" {
+  expect.to_not_be_defined ($response.optional_field)
+}
+```
+
+Checks that `$response.optional_field` is not defined.
+
+### `expect.to_be_null`
+
+```xs
+test "should be null" {
+  expect.to_be_null ($response.deleted_at)
+}
+```
+
+Checks that `$response.deleted_at` is `null`.
+
+### `expect.to_not_be_null`
+
+```xs
+test "should not be null" {
+  expect.to_not_be_null ($response.updated_at)
+}
+```
+
+Checks that `$response.updated_at` is not `null`.
+
+### `expect.to_be_empty`
+
+```xs
+test "should be empty" {
+  expect.to_be_empty ($response.items)
+}
+```
+
+Checks that `$response.items` is empty (array, string, etc).
+
+## Exception expects
+
+### `expect.to_throw`
+
+```xs
+test "should throw error" {
+  expect.to_throw {
+    value = "InvalidInputError"
+  }
+}
+```
+
+Checks that an error with value `"InvalidInputError"` was thrown.
+
+```xs
+test "should throw any error" {
+  expect.to_throw
+}
+```
+
+Checks that any error was thrown.
+
+## Mocking
+
+You can use the `mock` block inside your function or query to simulate external API responses or other data sources during unit testing. The mock will only be applied if its name matches the test name. This allows you to test your logic without making real network requests or depending on external systems.
+
+Mocks can be placed on any statement with a return value, such as API requests (`...} as $foo`), variable declarations (`var $x`), or variable updates (`var.update $x`). This gives you flexibility to mock data at any point in your logic.
+
+**Example with multiple tests and mocks:**
+
+```xs
+function get_weather {
+  input {
+    text city
+  }
+
+  stack {
+    api.request {
+      url = "https://api.weather.com/v1/current"
+      method = "GET"
+      params = {city: $input.city}
+      mock = {
+        "should return sunny weather": {response: {weather: "sunny"}}
+        "should return rainy weather": {response: {weather: "rainy"}}
+      }
+    } as $weather_response
+
+    var $weather_message {
+      value = "Today's weather is " ~ $weather_response.response.weather
+      mock = {
+        "should return sunny weather": "Today's weather is sunny"
+        "should return rainy weather": "Today's weather is rainy"
+      }
+    }
+  }
+
+  response = $weather_message
+
+  test "should return sunny weather" {
+    input = {city: "Paris"}
+
+    expect.to_equal ($response) {
+      value = "Today's weather is sunny"
+    }
+  }
+
+  test "should return rainy weather" {
+    input = {city: "London"}
+
+    expect.to_equal ($response) {
+      value = "Today's weather is rainy"
+    }
+  }
+}
+```
+
+** Example without mocks **
+
+```xs
+query "add_number" verb=GET {
+  input {
+    int a
+    int b
+  }
+
+  stack {
+    var $sum {
+      value = $input.a + $input.b
+    }
+  }
+
+  response = $sum
+
+  test "should add two numbers" {
+    input = {a: 5, b: 10}
+    expect.to_equal ($response) {
+      value = 15
+    }
+  }
+}
+
+**How mocking works:**
+
+- The `mock` block provides a fixed response for the statement it is attached to.
+- The mock is only used if its name matches the test name.
+- You can define multiple mocks for different test scenarios.
+- Mocks can be placed on API requests, variable declarations, or updates—any statement with a return value.
+- This ensures your tests run reliably and quickly, even when external services are unavailable.
+
+Use mocks to isolate your code from external dependencies and focus on your business logic.
+```

package/xanoscript_docs/version.json

@@ -0,0 +1,3 @@
+{
+  "version": "0.4.5"
+}

package/xanoscript_docs/workspace.md

@@ -0,0 +1,17 @@
+# XanoScript Workspace
+
+This document provides an overview of the XanoScript workspace structure and guidelines for organizing your XanoScript files within a VSCode environment. The workspace is designed to facilitate efficient development, version control, and collaboration.
+
+## Environment Variables
+
+Environment variables can be used in XanoScript by using the `$env` prefix. The user can set their own environment variables, Xano also provides some built-in environment variables. The following are some of the built-in environment variables:
+
+- `$env.$remote_ip`:this is a special environment variable that resolves to the IP address of the individual accessing the API endpoint.
+- `$env.$http_headers`:this is a text array of headers that are sent to the API endpoint.
+- `$env.$request_uri`:this is a special environment variable that contains the URI that is being accessed from the API.
+- `$env.$request_method`:this is the method (GET, POST, DELETE, etc) of the incoming API request.
+- `$env.$request_querystring`:this is a special environment variable that contains the query string of the URI that is being accessed from the API.
+- `$env.$datasource`:this is a special environment variable that contains which datasource is being used.
+- `$env.$branch`:this is a special environment variable that contains which branch is being used.
+
+Custom environment variables can be set in the Xano dashboard under Settings > Environment Variables. These variables can be accessed in XanoScript using the `$env` prefix followed by the variable name (e.g., `$env.MY_CUSTOM_VARIABLE`). When using custom environment variables ($env.SOME_SERVICE_API_KEY), You should inform the user to set them up in their Xano dashboard.