Skip to content

Commit fb55a28

Browse files
beezythebotbeezythebot
committed
Sync open source content 🐝 (from 9b3f3ed0daf5acc829fa65e2c817d3f820e00705)
1 parent f8f2236 commit fb55a28

File tree

12 files changed

+421
-15
lines changed

12 files changed

+421
-15
lines changed

‎_meta.global.tsx‎

Lines changed: 22 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -53,10 +53,10 @@ const meta = {
5353
title: "Getting Started",
5454
items: {
5555
typescript: {
56-
title: "Use TypeScript",
56+
title: "Use TypeScript (Gram Functions)",
5757
},
5858
openapi: {
59-
title: "Use an OpenAPI Spec",
59+
title: "Use an OpenAPI spec",
6060
},
6161
},
6262
},
@@ -86,15 +86,32 @@ const meta = {
8686
},
8787
},
8888
},
89+
"gram-functions": {
90+
title: "Gram Functions",
91+
items: {
92+
introduction: {
93+
title: "Introduction",
94+
},
95+
"functions-framework": {
96+
title: "Using the Functions Framework",
97+
},
98+
"mcp-sdk": {
99+
title: "Using the MCP SDK",
100+
},
101+
"build-deploy": {
102+
title: "Deploy as MCP",
103+
},
104+
},
105+
},
89106
"build-mcp": {
90107
title: "Build MCP",
91108
items: {
92-
"create-default-toolset": {
93-
title: "Create a default toolset",
94-
},
95109
"custom-toolsets": {
96110
title: "Curate a custom toolset",
97111
},
112+
"create-default-toolset": {
113+
title: "Create a default toolset",
114+
},
98115
"advanced-tool-curation": {
99116
title: "Advanced tool curation",
100117
},

‎docs/gram/getting-started/typescript.mdx‎

Lines changed: 105 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,112 @@
11
---
2-
title: "Create an MCP Server using the TypeScript Framework"
2+
title: "Create an MCP Server using the TypeScript Framework (Gram Functions)"
33
description: "Learn how to create and deploy an MCP server using Gram's TypeScript framework."
44
---
55

6-
## 🚧 Coming Soon! 🚧
6+
import { Callout } from "@/mdx/components";
77

8-
Gram's Functions and TypeScript Framework are currently under active
9-
development. Check back in the coming days for a detailed guide on getting
10-
started using these developer tools.
8+
Welcome! This guide will walk you through the process of creating tools and a MCP server using Gram Functions.
9+
Gram Functions allows you to deploy completely isolated tool call environments that can then be exposed as MCP servers.
1110

12-
In the meantime, check out the following resources:
11+
```typescript filename="gram.ts"
12+
import { Gram } from "@gram-ai/functions";
13+
import * as z from "zod/mini";
1314

14-
- [GitHub Repository: Gram TypeScript Framework](https://github.com/speakeasy-api/gram/tree/main/ts-framework)
15-
- [Core Concepts: Gram Functions](/docs/gram/concepts/tool-sources#gram-functions)
16-
- [Gram CLI](/docs/gram/command-line/installation)
17-
- [Getting Started: OpenAPI](/docs/gram/getting-started/openapi)
15+
const gram = new Gram().tool({
16+
name: "greet",
17+
description: "Greet someone special",
18+
inputSchema: { name: z.string() },
19+
async execute(ctx, input) {
20+
return ctx.text(`Hello, ${input.name}!`);
21+
},
22+
});
23+
24+
export default gram;
25+
```
26+
27+
## Step 1: Create a project
28+
29+
Gram offers a bootstrapper through `npm/pnpm create` to create a new project.
30+
31+
<Callout title="Note" type="info">
32+
Gram Functions currently requires a node version >=22.18.0
33+
</Callout>
34+
35+
```bash
36+
npm create @gram-ai/function
37+
```
38+
39+
This will prompt you to pick a framework.
40+
```bash
41+
◆ Pick a framework
42+
│ ● Gram (Default. A simple framework to get started quickly)
43+
│ ○ MCP (Gram also supports the official MCP SDK for more advanced use cases)
44+
```
45+
46+
This will create a new project in the current directory.
47+
```bash
48+
cd my-mcp-server
49+
```
50+
51+
Inside your project, you'll find the following files:
52+
```bash
53+
└── src
54+
├── gram.ts <- Edit me!
55+
└── server.ts
56+
└── package.json
57+
└── README.md
58+
...
59+
```
60+
61+
## Step 2: Write your tools
62+
63+
Open `src/gram.ts` and write your tools. You can add as many tools as you want, or leave it as-is to use the default tool. For more information on writing tools, see the [Gram Functions](/docs/gram/gram-functions/introduction) documentation.
64+
65+
```typescript filename="src/gram.ts"
66+
import { Gram } from "@gram-ai/functions";
67+
import * as z from "zod/mini";
68+
69+
const gram = new Gram().tool({
70+
name: "greet",
71+
description: "Greet someone special",
72+
inputSchema: { name: z.string() },
73+
async execute(ctx, input) {
74+
return ctx.json({ message: `Hello, ${input.name}!` });
75+
},
76+
});
77+
78+
export default gram;
79+
```
80+
81+
<Callout title="Note" type="info">
82+
You are not necessarily building an MCP server here. Write whatever tools you want--you will later be able
83+
to slice and dice them into MCP servers or combine them with other types of tools into existing MCP servers.
84+
</Callout>
85+
86+
## Step 3: Build and deploy
87+
88+
To build and deploy your MCP server, run the following commands:
89+
90+
```bash
91+
npm run build
92+
npm run push
93+
```
94+
95+
This will build your functions and deploy them to Gram. In the [Gram Dashboard](https://app.getgram.ai), you will see the function source you just uploaded and the tools it created.
96+
97+
![Gram Dashboard, showing the function source you just uploaded](/assets/docs/gram/img/functions/onboarding_functions-pushed.png)
98+
99+
## Step 4: Create an MCP server
100+
101+
You can now add your tools to an existing MCP server or create a new one.
102+
103+
To create a new MCP server, go to the Toolsets page and click **Create A Toolset** (or **+ Add Toolset**). Name it whatever you want. A toolset is a group of tools that can be exposed as an MCP server.
104+
For more information on toolsets, see the [Toolsets](/docs/gram/build-mcp) documentation.
105+
106+
![Gram Dashboard, showing the create toolset dialog](/assets/docs/gram/img/functions/onboarding_create-toolset.png)
107+
108+
Now, click **Add Tools** to add your tools to the toolset. You'll see the tools you defined in your `src/gram.ts` file listed here.
109+
110+
![Gram Dashboard, showing the add tools dialog](/assets/docs/gram/img/functions/onboarding_add-tools.png)
111+
112+
Finally, head to the **MCP** tab on the toolset page and click **Enable**. Check out the **Install Page** linked therein for help installing the MCP server in your favorite client. For more information on MCP servers, see the [MCP Servers](/docs/gram/host-mcp) documentation.

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

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: "Build and Deploy"
3+
description: "Learn how to build, test, and deploy your Gram Functions to production."
4+
---
5+
6+
import { Callout } from "@/mdx/components";
7+
8+
Deploying Gram Functions is as simple as writing them. Deploying will upload your code to Gram and create the tools you've defined.
9+
You can then take advantage of all the Gram platform offers to host your tools as MCP servers, combine them into toolsets, build multi-tool workflows, and more.
10+
11+
<Callout title="Note" type="info">
12+
Your functions to not need to be organized as a single MCP server. They will be deployed to Gram as individual tools that can be split apart or combined into MCP servers in the Gram dashboard.
13+
</Callout>
14+
15+
16+
## Build
17+
18+
To build your tools, run the following command:
19+
20+
```bash
21+
npm run build
22+
```
23+
24+
This will compile your tools into a zip file that can be deployed to Gram.
25+
26+
## Deploy
27+
28+
To deploy yout tools to Gram, run the following command:
29+
30+
```bash
31+
npm run push
32+
```
33+
34+
This will upload your tools to Gram and create the tools you've defined. In the [Gram Dashboard](https://app.getgram.ai), you will see the function source you just uploaded and the tools it created.
35+
36+
![Gram Dashboard, showing the function source you just uploaded](/assets/docs/gram/img/functions/onboarding_functions-pushed.png)
37+
38+
## Next steps
39+
40+
Now that you've deployed your tools, you can start using them in MCP servers, combine them into toolsets, build multi-tool workflows, and more. Head to the [Build MCP](/docs/gram/build-mcp/custom-toolsets) documentation to learn more.

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

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: "Using the Functions Framework"
3+
description: "Learn how to use Gram's Functions Framework with TypeScript, including context objects and best practices."
4+
---
5+
6+
## Overview
7+
8+
The Gram Functions Framework provides a streamlined way to build MCP tools using TypeScript. It handles the MCP protocol implementation while letting you focus on your tool logic.
9+
10+
![Choosing the Gram Framework](/assets/docs/gram/img/functions/npm_gram-framework.png)
11+
12+
## Function structure
13+
14+
Every Gram Function follows this basic structure:
15+
16+
```typescript filename="gram.ts"
17+
import { Gram } from "@gram-ai/functions";
18+
import * as z from "zod/mini";
19+
20+
const gram = new Gram().tool({
21+
name: "add",
22+
description: "Add two numbers together",
23+
inputSchema: { a: z.number(), b: z.number() },
24+
async execute(ctx, input) {
25+
return ctx.json({sum: input.a + input.b});
26+
},
27+
});
28+
29+
export default gram;
30+
```
31+
32+
## Environment Variables
33+
34+
With Gram functions you can specify credentials or envrionment variable values that will need to be provided to your tool runner.
35+
These can be provided either by end user set MCP headers or with stored Gram environments.
36+
37+
```typescript
38+
const gram = new Gram({
39+
envSchema: {
40+
BASE_URL: z.string().check(z.url()),
41+
},
42+
}).tool({
43+
name: "api_call",
44+
inputSchema: { endpoint: z.string() },
45+
async execute(ctx, input) {
46+
const baseURL = ctx.env?.["BASE_URL"];
47+
// Use baseURL...
48+
},
49+
});
50+
```
51+
52+
53+
## Using Fetch
54+
55+
With Gram functions you can make requests to downstream APIs and respond with the result.
56+
57+
```typescript
58+
const gram = new Gram()
59+
.tool({
60+
name: "spacex-ships",
61+
description: "Get the latest SpaceX ship list",
62+
inputSchema: {},
63+
async execute(ctx) {
64+
return fetch("https://api.spacexdata.com/v3/ships");
65+
},
66+
});
67+
```
68+
69+
## Next steps
70+
- [Build and deploy](/docs/gram/gram-functions/build-deploy)

‎docs/gram/gram-functions/introduction.mdx‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
title: "Gram Functions"
3+
description: "Build custom tools with TypeScript functions for complete control over logic and dependencies."
4+
---
5+
6+
Gram Functions allow you to create tools from TypeScript code.
7+
Once deployed, they can be used just like any other tool in the Gram platform, allowing you to create and host MCP servers,
8+
combine them with other tools into toolsets, build multi-tool workflows, and more.
9+
10+
```typescript filename="gram.ts"
11+
import { Gram } from "@gram-ai/functions";
12+
import * as z from "zod/mini";
13+
14+
const gram = new Gram().tool({
15+
name: "greet",
16+
description: "Greet someone special",
17+
inputSchema: { name: z.string() },
18+
async execute(ctx, input) {
19+
return ctx.text(`Hello, ${input.name}!`);
20+
},
21+
});
22+
23+
export default gram;
24+
```
25+
26+
## Getting started
27+
28+
To get started with Gram Functions, follow the [Getting Started](/docs/gram/getting-started/typescript) guide.
29+
30+
```bash
31+
npm create @gram-ai/function
32+
```
33+
34+
## Writing tools
35+
36+
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).
37+
The Functions Framework is a more lightweight way to write tools, while MCP SDK support is available if you prefer to use the official SDK.
38+
39+
```typescript filename="gram-framework.ts"
40+
import { Gram } from "@gram-ai/functions";
41+
import * as z from "zod/mini";
42+
43+
const gram = new Gram().tool({
44+
name: "greet",
45+
description: "Greet someone special",
46+
inputSchema: { name: z.string() },
47+
async execute(ctx, input) {
48+
return ctx.text(`Hello, ${input.name}!`);
49+
},
50+
});
51+
52+
export default gram;
53+
```
54+
55+
## Deploying to Gram
56+
57+
Gram allows you to easily deploy and host your tools. Beyond hosting and running code for you,
58+
Gram offers a comprehensive set of features to help you build on top of your tools and deliver a powerful AI-native experience to your users.
59+
Follow the [Build and deploy](/docs/gram/gram-functions/build-deploy) guide to learn more.
60+
61+
```bash
62+
npm run build
63+
npm run push
64+
```
65+
66+
## Functions vs. MCP Servers
67+
68+
Gram Functions are a great way to create tools that can be used in MCP servers.
69+
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.
70+
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.
71+
However, they are not the only way to create tools. You can also directly from OpenAPI documents.
72+
73+
### Local development
74+
75+
With that said, Gram Functions can be run as a local MCP server with [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) for testing and development purposes. Simply run:
76+
77+
```bash
78+
pnpm run dev
79+
```

0 commit comments

Comments
 (0)