feature: add tutorial examples

src/main/java/io/naftiko/engine/README.md

@@ -33,12 +33,17 @@ There are 3 ways to use the Framework Engine, depending on your goal.
 * Create your capability configuration file.\
   The Framework Engine runs capabilities. For that, it uses a capability configuration file. You first have to create this file locally according to the [specification](/src/main/resources/schemas/README.md). This file must be a yaml or json file (yaml, yml, and json extensions are supported).
 
-* Local hosts in your capability configuration file.\
-  If your capability reffers to some local hosts, be carefull to not use 'localhost', but 'host.docker.internal' instead. This is because your capability will run into an isolated docker container, so 'localhost' will reffer to the container and not your local machine.
-  For example:
-  ```bash
-  baseUri: "http://host.docker.internal:8080/api/"
-  ```
+* Localhost in your capability configuration file.
+  * If your capability reffers to some local hosts, be carefull to not use 'localhost', but 'host.docker.internal' instead. This is because your capability will run into an isolated docker container, so 'localhost' will reffer to the container and not your local machine.\
+    For example:
+    ```bash
+    baseUri: "http://host.docker.internal:8080/api/"
+    ```
+  * In the same way, if your capability expose a local host, be careful to not use 'localhost', but '0.0.0.0' instead. Else requests to localhost coming from outside of the container won't succeed.\
+    For example:
+    ```bash
+    address: "0.0.0.0"
+    ```
 
 #### Run the Framework Engine as a docker container
 * Use a docker volume.\

src/main/resources/schemas/tutorial/step-1-my-first-capability.yml

@@ -0,0 +1,16 @@
+naftiko: "0.5"
+capability:
+  exposes:
+    - type: "api"
+      port: 8081
+      namespace: "tutorial"
+      resources:
+        - path: "/hello"
+          name: "hello"
+          label: "My first resource"
+          description: "This is a resource to demonstrate a simple Hello, World! API endpoint"
+          operations:
+            - method: "GET"
+              outputParameters:
+                - type: "string"
+                  const: "Hello, World!"

src/main/resources/schemas/tutorial/step-2-forwarding-api-resource.yml

@@ -0,0 +1,19 @@
+naftiko: "0.5"
+capability:
+  exposes:
+    - type: "api"
+      port: 8081
+      namespace: "sample"
+      resources:
+        - path: "/notion/{{path}}"
+          description: "This resource forwards requests to the Notion API, allowing access to any Notion endpoint by specifying the path parameter. For example, a request to /notion/pages would be forwarded to https://api.notion.com/v1/pages."
+          forward:
+            targetNamespace: notion
+            trustedHeaders:
+            - Notion-Version
+
+  consumes:
+    - type: "http"
+      description: "Forwarded requests from the /notion/{path} resource, to be sent to the Notion API"
+      namespace: "notion"
+      baseUri: "https://api.notion.com/v1/"

src/main/resources/schemas/tutorial/step-3-encapsulating-headers.yml

@@ -0,0 +1,26 @@
+naftiko: "0.5"
+capability:
+  exposes:
+    - type: "api"
+      port: 8081
+      namespace: "sample"
+      resources:
+        - path: "/notion/{{path}}"
+          description: "This resource forwards requests to the Notion API, allowing access to any Notion endpoint by specifying the path parameter. For example, a request to /notion/pages would be forwarded to https://api.notion.com/v1/pages."
+          forward:
+            targetNamespace: notion
+
+  consumes:
+    - type: "http"
+      description: "Forwarded requests from the /notion/{path} resource, to be sent to the Notion API"
+      namespace: "notion"
+      baseUri: "https://api.notion.com/v1/"
+      authentication:
+        type: "bearer"
+        token: "{{notion_api_key}}"
+      inputParameters:
+        - name: "notion_api_key"
+          in: "environment"
+        - name: "Notion-Version"
+          in: "header"
+          value: "2025-09-03"

src/main/resources/schemas/tutorial/step-4-filter-reponse.yml

@@ -0,0 +1,47 @@
+naftiko: "0.5"
+capability:
+  exposes:
+    - type: "api"
+      port: 8081
+      namespace: "sample"
+      resources:
+        - path: "/notion/users/me"
+          description: "This resource is for the specific path /notion/users/me and restricted to nested operations."
+          forward:
+            targetNamespace: notion
+          operations:
+            - method: "GET"
+              call: "notion.get-me"
+              outputParameters:
+                - type: "object"
+                  properties:
+                    id:
+                      type: "string"
+                      mapping: "$.id"
+                    name:
+                      type: "string"
+                      mapping: "$.name"
+                    type:
+                      type: "string"
+                      mapping: "$.type"
+
+  consumes:
+    - type: "http"
+      description: "Forwarded requests from the /notion/{path} resource, to be sent to the Notion API"
+      namespace: "notion"
+      baseUri: "https://api.notion.com/v1/"
+      authentication:
+        type: "bearer"
+        token: "{{notion_api_key}}"
+      inputParameters:
+        - name: "notion_api_key"
+          in: "environment"
+        - name: "Notion-Version"
+          in: "header"
+          value: "2025-09-03"
+      resources:
+        - path: "users/me"
+          name: "users-me"
+          operations:
+            - method: "GET"
+              name: "get-me"

src/main/resources/schemas/tutorial/step-5-multi-steps.yml

@@ -0,0 +1,68 @@
+naftiko: "0.5"
+info:
+  label: "Tutorial - Step 5 - Multi steps"
+  description: "This capability is based on two resources called one after the other. The second step takes an output value of the first one as argument (user_id)"
+  tags:
+    - Naftiko
+    - Tutorial
+  created: "2026-02-26"
+  modified: "2026-03-04"
+  stakeholders:
+    - role: "editor"
+      fullName: "Navi"
+      email: "navi@naftiko.io"
+
+capability:
+  exposes:
+    - type: "api"
+      port: 8081
+      namespace: "my-capability"
+      resources:
+        - path: "/notion/my-full-user"
+          description: "This resource is for the specific path /notion/my-full-user and restricted to nested operations."
+          forward:
+            targetNamespace: notion
+          operations:
+            - method: "GET"
+              steps:
+                - name: "fetch-me-user"
+                  type: "call"
+                  call: "notion.get-me"
+                - name: "fetch-user-by-id"
+                  type: "call"
+                  call: "notion.get-user"
+                  with:
+                    user_id: "{{fetch-me-user.userid}}"
+
+  consumes:
+    - type: "http"
+      description: "Forwarded requests from the /notion/{path} resource, to be sent to the Notion API"
+      namespace: "notion"
+      baseUri: "https://api.notion.com/v1/"
+      authentication:
+        type: "bearer"
+        token: "{{notion_api_key}}"
+      inputParameters:
+        - name: "notion_api_key"
+          in: "environment"
+        - name: "Notion-Version"
+          in: "header"
+          value: "2025-09-03"
+      resources:
+        - path: "users/me"
+          name: "users-me"
+          operations:
+            - method: "GET"
+              name: "get-me"
+              outputParameters:
+                - name: "userid"
+                  type: "string"
+                  value: "$.id"
+        - path: "users/{{user_id}}"
+          name: "users-by-id"
+          inputParameters:
+            - name: "user_id"
+              in: "path"
+          operations:
+            - method: "GET"
+              name: "get-user"

src/main/resources/schemas/tutorial/step-6-mcp.yml

@@ -0,0 +1,90 @@
+naftiko: "0.5"
+info:
+  label: "Tutorial - Step 6 - MCP"
+  description: "This is a sample capability specification to demonstrate the MCP exposition feature"
+  tags:
+    - Naftiko
+    - Tutorial
+  created: "2026-03-05"
+  modified: "2026-03-05"
+  stakeholders:
+    - role: "editor"
+      fullName: "Navi"
+      email: "navi@naftiko.io"
+
+capability:
+  exposes:
+    - type: "mcp"
+      address: "0.0.0.0"
+      port: 9091
+      namespace: "notion-mcp"
+      description: "MCP server exposing Notion database query capabilities for pre-release participant management."
+
+      tools:
+        - name: "query-database"
+          description: "Query the Notion pre-release participants database to retrieve committed participants with their name, company, title, location, owner, participation status and comments."
+          call: "notion.query-db"
+          with:
+            datasource_id: "2fe4adce-3d02-8028-bec8-000bfb5cafa2"
+          outputParameters:
+            - type: "array"
+              mapping: "$.results"
+              items:
+                - type: "object"
+                  properties:
+                    name:
+                      type: "string"
+                      mapping: "$.properties.Name.title[0].text.content"
+                    company:
+                      type: "string"
+                      mapping: "$.properties.Company.rich_text[0].text.content"
+                    title:
+                      type: "string"
+                      mapping: "$.properties.Title.rich_text[0].text.content"
+                    location:
+                      type: "string"
+                      mapping: "$.properties.Location.rich_text[0].text.content"
+                    owner:
+                      type: "string"
+                      mapping: "$.properties.Owner.people[0].name"
+                    participation_status:
+                      type: "string"
+                      mapping: "$.properties.Participation Status.select.name"
+                    comments:
+                      type: "string"
+                      mapping: "$.properties.Comments.rich_text[0].text.content"
+
+  consumes:
+    - type: "http"
+      description: "Notion API integration for accessing pre-release participant data stored in Notion."
+      namespace: "notion"
+      baseUri: "https://api.notion.com/v1/"
+      authentication:
+        type: "bearer"
+        token: "{{notion_api_key}}"
+      inputParameters:
+        - name: "notion_api_key"
+          in: "environment"
+        - name: "Notion-Version"
+          in: "header"
+          value: "2025-09-03"
+      resources:
+        - inputParameters:
+            - name: datasource_id
+              in: "path"
+          path: "data_sources/{{datasource_id}}/query"
+          name: "query"
+          label: "Query database resource"
+          operations:
+            - method: "POST"
+              name: "query-db"
+              label: "Query Database"
+              body: |
+                {
+                  "filter": {
+                    "property": "Participation Status",
+                    "select": {
+                      "equals": "Committed"
+                    }
+                  }
+                }