Sync open source content 🐝 (from d9c61d3e8b46cac17a711c97c1b4f95565a1bdd9)

Author: beezythebot

docs/gram/gram-functions/build-deploy.mdx

@@ -25,7 +25,7 @@ This will compile your tools into a zip file that can be deployed to Gram.
 
 ## Deploy
 
-To deploy yout tools to Gram, run the following command:
+To deploy your tools to Gram, run the following command:
 
 ```bash
 npm run push

docs/gram/gram-functions/functions-framework.mdx

@@ -29,41 +29,148 @@ const gram = new Gram().tool({
 export default gram;
 ```
 
-## Environment Variables
+## Tool definition
 
-With Gram functions you can specify credentials or envrionment variable values that will need to be provided to your tool runner.
-These can be provided either by end user set MCP headers or with stored Gram environments.
+Each tool requires the following properties:
+
+- **name**: Unique identifier for the tool
+- **description** (optional): Human-readable explanation of what the tool does
+- **inputSchema**: Zod schema defining the expected input parameters
+- **execute**: Async function that implements the tool logic
+
+## Context object
+
+The execute function receives a context object with several helper methods for handling responses and accessing configuration:
+
+### Response methods
+
+- **ctx.json(data)**: Returns a JSON response
+- **ctx.text(data)**: Returns a plain text response
+- **ctx.html(data)**: Returns an HTML response
+- **ctx.fail(data, options?)**: Throws an error response
+
+```typescript
+const gram = new Gram().tool({
+  name: "format_data",
+  inputSchema: { format: z.enum(["json", "text", "html"]), data: z.string() },
+  async execute(ctx, input) {
+    if (input.format === "json") {
+      return ctx.json({ data: input.data });
+    } else if (input.format === "text") {
+      return ctx.text(input.data);
+    } else {
+      return ctx.html(`<div>${input.data}</div>`);
+    }
+  },
+});
+```
+
+### Additional context properties
+
+- **ctx.signal**: AbortSignal for handling cancellation
+- **ctx.env**: Access to parsed environment variables
+
+```typescript
+const gram = new Gram().tool({
+  name: "long_running_task",
+  inputSchema: { url: z.string() },
+  async execute(ctx, input) {
+    try {
+      const response = await fetch(input.url, { signal: ctx.signal });
+      return ctx.json(await response.json());
+    } catch (error) {
+      if (error.name === "AbortError") {
+        return ctx.fail("Request was cancelled");
+      }
+      throw error;
+    }
+  },
+});
+```
+
+## Input validation
+
+The framework validates inputs against the provided Zod schema by default. For strict validation, inputs that don't match the schema will be rejected.
+
+### Lax mode
+
+To allow unvalidated inputs, enable lax mode:
+
+```typescript
+const gram = new Gram({ lax: true }).tool({
+  name: "flexible_tool",
+  inputSchema: { required: z.string() },
+  async execute(ctx, input) {
+    // input may contain additional properties not in the schema
+    return ctx.json({ received: input });
+  },
+});
+```
+
+## Environment variables
+
+Specify credentials or environment variable values that need to be provided to the tool runner. These can be provided either by end user set MCP headers or with stored Gram environments.
 
 ```typescript
 const gram = new Gram({
   envSchema: {
-    BASE_URL: z.string().check(z.url()),
+    API_KEY: z.string().describe("API key for authentication"),
+    BASE_URL: z.string().url().describe("Base URL for API requests"),
   },
 }).tool({
   name: "api_call",
   inputSchema: { endpoint: z.string() },
   async execute(ctx, input) {
+    const apiKey = ctx.env?.["API_KEY"];
     const baseURL = ctx.env?.["BASE_URL"];
-    // Use baseURL...
+
+    const response = await fetch(`${baseURL}${input.endpoint}`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+    });
+
+    return ctx.json(await response.json());
+  },
+});
+```
+
+For testing purposes, environment variables can be overridden via the `env` parameter. Otherwise, they default to `process.env`.
+
+## Using fetch
+
+Tools can make requests to downstream APIs and respond with the result:
+
+```typescript
+const gram = new Gram().tool({
+  name: "spacex-ships",
+  description: "Get the latest SpaceX ship list",
+  inputSchema: {},
+  async execute(ctx) {
+    const response = await fetch("https://api.spacexdata.com/v3/ships");
+    return ctx.json(await response.json());
   },
 });
 ```
 
+## Response flexibility
 
-## Using Fetch
+Tools can return responses in multiple formats:
 
-With Gram functions you can make requests to downstream APIs and respond with the result.
+- JSON responses via `ctx.json()`
+- Plain text via `ctx.text()`
+- HTML content via `ctx.html()`
+- Custom Web API Response objects with specific headers and status codes
 
 ```typescript
-const gram = new Gram()
-  .tool({
-    name: "spacex-ships",
-    description: "Get the latest SpaceX ship list",
-    inputSchema: {},
-    async execute(ctx) {
-      return fetch("https://api.spacexdata.com/v3/ships");
-    },
-  });
+const gram = new Gram().tool({
+  name: "custom_response",
+  inputSchema: { code: z.number() },
+  async execute(ctx, input) {
+    return new Response("Custom response", {
+      status: input.code,
+      headers: { "X-Custom-Header": "value" },
+    });
+  },
+});
 ```
 
 ## Next steps

docs/gram/gram-functions/introduction.mdx

@@ -3,9 +3,7 @@ title: "Gram Functions"
 description: "Build custom tools with TypeScript functions for complete control over logic and dependencies."
 ---
 
-Gram Functions allow you to create tools from TypeScript code. 
-Once deployed, they can be used just like any other tool in the Gram platform, allowing you to create and host MCP servers, 
-combine them with other tools into toolsets, build multi-tool workflows, and more.
+Gram Functions are compact code units that represent LLM tools. They allow you to create tools from TypeScript code that can be deployed to Gram and exposed to language models via MCP servers. Once deployed, they can be used just like any other tool in the Gram platform, allowing you to create and host MCP servers, combine them with other tools into toolsets, build multi-tool workflows, and more.
 
 ```typescript filename="gram.ts"
 import { Gram } from "@gram-ai/functions";
@@ -25,12 +23,20 @@ export default gram;
 
 ## Getting started
 
-To get started with Gram Functions, follow the [Getting Started](/docs/gram/getting-started/typescript) guide.
+To get started with Gram Functions, scaffold a new project using the Gram template:
 
 ```bash
-npm create @gram-ai/function
+pnpm create @gram-ai/function@latest --template gram
 ```
 
+Install the required package:
+
+```bash
+pnpm add @gram-ai/functions
+```
+
+For a complete walkthrough, follow the [Getting Started](/docs/gram/getting-started/typescript) guide.
+
 ## Writing tools
 
 Gram Functions can be written using the [Gram Functions Framework](/docs/gram/gram-functions/functions-framework) or the official [MCP SDK](/docs/gram/gram-functions/mcp-sdk).
@@ -63,12 +69,22 @@ npm run build
 npm run push
 ```
 
-## Functions vs. MCP Servers
+## Functions vs. MCP servers
+
+Gram Functions are a way to create individual tools that can be used in MCP servers. However, creating tools in Gram is not the same as creating MCP servers.
+
+The key distinction:
+
+- **Functions**: Individual tools that represent specific capabilities or operations
+- **MCP Servers**: Collections of tools combined into a single server that can be accessed by LLM clients
+
+Once you have created a tool (via Functions or OpenAPI), combine it with other tools into one or many MCP servers. This means you can:
+
+- Split your Gram functions into multiple projects for convenience
+- Keep every tool in one file
+- Organize tools however makes sense for your workflow
 
-Gram Functions are a great way to create tools that can be used in MCP servers. 
-However, creating tools in Gram is not the same as creating MCP servers. Once you have created a tool (via Functions or OpenAPI), you can combine it with other tools into one (or many) MCP servers.
-You can therefore split your Gram functions into multiple projects for convenience, or keep every tool in one file. MCP servers will be created from [toolsets](/docs/gram/concepts/toolsets) later in the Gram dashboard.
-However, they are not the only way to create tools. You can also directly from OpenAPI documents.
+MCP servers are created from [toolsets](/docs/gram/concepts/toolsets) later in the Gram dashboard. Tools can also be created directly from OpenAPI documents.
 
 ### Local development
 

docs/gram/gram-functions/mcp-sdk.mdx

@@ -85,10 +85,9 @@ server.registerResource(
 After running `push` simply select that resource to add it to a toolset.
 ![Adding a Resource](/assets/docs/gram/img/functions/adding-resources.png)
 
-## Environment Variables
+## Environment variables
 
-You can specify credentials or envrionment variable values that will need to be made available in your tool runner envrionment.
-These can be provided either by end user set MCP headers or with stored Gram environments.
+Specify credentials or environment variable values that need to be made available in your tool runner environment. These can be provided either by end user set MCP headers or with stored Gram environments.
 
 ```typescript filename="gram.ts"
 import { withGram } from "@gram-ai/functions/mcp";