You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Updates the readme to fix the following:
- Fix broken links to some documentation pages
- Better hierarchy for different sub products
- Stronger messaging in the introductory sections and better CTAs
- Fix formatting issues
- Move contributor/local dev instructions to the `CONTRIBUTING.md` file
Run `./zero` until it succeeds. This script is what you will use to run the dashboard and services for local development. It will also handle installing dependencies and running pending database migrations before starting everything up.
4
+
5
+
The main dependencies for this project are Mise and Docker. The `./zero` script will guide you to install these if they are not found.
6
+
7
+
### CLI development
8
+
9
+
Quickstart:
10
+
11
+
```bash
12
+
cd cli
13
+
go run . --help
14
+
```
15
+
1
16
# Contribution guidelines
2
17
3
-
Above anything else in this document: we do not perfectly hold to the guidelines
4
-
below but we do our best to work towards them. Active codebases will readily
5
-
deteriorate with time unless explicit efforts are made to reverse deterioration.
18
+
Above anything else in this document: we do not perfectly hold to the guidelines below but we do our best to work towards them. Active codebases will readily deteriorate with time unless explicit efforts are made to reverse deterioration.
6
19
7
-
Good and bad decisions compound and the goal of this document is to get you
8
-
making good decisions that help build Gram up as a useful and high-quality
9
-
product.
20
+
Good and bad decisions compound and the goal of this document is to get you making good decisions that help build Gram up as a useful and high-quality product.
10
21
11
22
## Preamble
12
23
@@ -15,27 +26,15 @@ product.
15
26
16
27
**The world is full of APIs that we want AI agents to leverage effectively.**
17
28
18
-
Gram is an exploration into how we can take that vast space of APIs and create
19
-
the right bridges to them for AI agents. We welcome ideas as much as code
20
-
contributions that serve this goal.
29
+
Gram is an exploration into how we can take that vast space of APIs and create the right bridges to them for AI agents. We welcome ideas as much as code contributions that serve this goal.
21
30
22
31
**Open source as a team effort.**
23
32
24
-
The goal of open sourcing Gram is to recognize that we solve problems better
25
-
as a community rather than as a walled off teams and give confidence to those
26
-
that want to use the service either through Speakeasy or self-hosted. For Gram
27
-
to succeed as useful product, we want to welcome contributors that share our
28
-
values and goals around building high-quality products for the Agentic AI
29
-
frontier.
33
+
The goal of open sourcing Gram is to recognize that we solve problems better as a community rather than as a walled off teams and give confidence to those that want to use the service either through Speakeasy or self-hosted. For Gram to succeed as useful product, we want to welcome contributors that share our values and goals around building high-quality products for the Agentic AI frontier.
30
34
31
35
**High quality products are built from high quality decisions.**
32
36
33
-
The goal of these guidelines and any roadmap plans made in Gram is to ensure we
34
-
are solving the right problems to connect AI agents to the sprawl of APIs in the
35
-
world. This may mean we choose to work on some things over others or reject
36
-
proposals that we do not believe serve this goal. We encourage productive
37
-
discussions and opinions that are grounded in research and ultimately lead us
38
-
to make good decisions when building Gram.
37
+
The goal of these guidelines and any roadmap plans made in Gram is to ensure we are solving the right problems to connect AI agents to the sprawl of APIs in the world. This may mean we choose to work on some things over others or reject proposals that we do not believe serve this goal. We encourage productive discussions and opinions that are grounded in research and ultimately lead us to make good decisions when building Gram.
39
38
40
39
</details>
41
40
@@ -46,61 +45,33 @@ to make good decisions when building Gram.
46
45
47
46
**Readability, maintainability, strong conventions and the long view.**
48
47
49
-
We want to be fast at every stage of developing Gram. We're not going to over-
50
-
index on throwing code into production with no checks and balances when it means
51
-
we'll sink into a tarpit of bugs and incidents months from now. There is a
52
-
widely-applicable definition of "fast iteration speed" that includes not making
53
-
messes along the way. Establishing guardrails and conventions in coding and
54
-
codebase structure means we can increase our iteration speed by adding well-
55
-
aligned contributors. Everyone will benefit from this: current and future
56
-
users and contributors.
48
+
We want to be fast at every stage of developing Gram. We're not going to over-index on throwing code into production with no checks and balances when it means we'll sink into a tarpit of bugs and incidents months from now. There is a widely-applicable definition of "fast iteration speed" that includes not making messes along the way. Establishing guardrails and conventions in coding and codebase structure means we can increase our iteration speed by adding well-aligned contributors. Everyone will benefit from this: current and future users and contributors.
57
49
58
50
**You are the first reviewer of your AI assistant's contributions.**
59
51
60
-
You are responsible for all the work that you and your assistants produce. You
61
-
must be the first reviewer of all your work before requesting reviews from
62
-
anyone else.
52
+
You are responsible for all the work that you and your assistants produce. You must be the first reviewer of all your work before requesting reviews from anyone else.
63
53
64
54
**Add tests for all new contributions.**
65
55
66
-
Coding agents and assistants are fantastically effective at this. Utilize them
67
-
if you can but always review their work to ensure that they are indeed testing
68
-
the changes you/they make. The goal is not to hit 100% test coverage but to have
69
-
higher and higher confidence that the code you write does what you expect it to
70
-
do and enable others to maintain it well.
56
+
Coding agents and assistants are fantastically effective at this. Utilize them if you can but always review their work to ensure that they are indeed testing the changes you/they make. The goal is not to hit 100% test coverage but to have higher and higher confidence that the code you write does what you expect it to do and enable others to maintain it well.
71
57
72
58
**Add documentation whenever possible.**
73
59
74
-
We document how we deploy Gram, how we manage the database schema and migrations
75
-
and how we manage infrastructure. A lot of this documentation should act as a
76
-
sort of runbook that aids new contributors and incident responders. If you are
77
-
materially affecting any of these areas, please add documentation to help others
78
-
understand how to operate Gram.
60
+
We document how we deploy Gram, how we manage the database schema and migrations and how we manage infrastructure. A lot of this documentation should act as a sort of runbook that aids new contributors and incident responders. If you are materially affecting any of these areas, please add documentation to help others understand how to operate Gram.
79
61
80
62
**Code comments are great.**
81
63
82
-
We are not prescriptive about code comments but we encourage them. Particularly
83
-
on methods and exported types since these greatly help coding assistants
84
-
understand the codebase without having to always to consider all logic.
64
+
We are not prescriptive about code comments but we encourage them. Particularly on methods and exported types since these greatly help coding assistants understand the codebase without having to always to consider all logic.
85
65
86
66
**Code reviews are great.**
87
67
88
-
We review all contributions to Gram and will favor pull requests that are small
89
-
and focused over massive and far reaching ones. We have no preference or
90
-
expectations for how you structure your commits since we squash all commits on
91
-
merge. We do however appreciate contributors that spend any time to structure
92
-
their work if size of change is large.
68
+
We review all contributions to Gram and will favor pull requests that are small and focused over massive and far reaching ones. We have no preference or expectations for how you structure your commits since we squash all commits on merge. We do however appreciate contributors that spend any time to structure their work if size of change is large.
93
69
94
-
Above all, we expect folks to spend non-zero effort adding a meaningful pull
95
-
request title and description since these will contribute to the changelog.
70
+
Above all, we expect folks to spend non-zero effort adding a meaningful pull request title and description since these will contribute to the changelog.
96
71
97
72
**Too much nesting kills readability.**
98
73
99
-
Our brains are very slow code interpreters. We can help them along by managing
100
-
code complexity to optimize for readability. _Functions that have 4 or more
101
-
levels of nested code where branches have substantial amounts of business
102
-
logic are heavily discouraged._ The contrived example below is the upper bound
103
-
of what we consider comprehensible code:
74
+
Our brains are very slow code interpreters. We can help them along by managing code complexity to optimize for readability. _Functions that have 4 or more levels of nested code where branches have substantial amounts of business logic are heavily discouraged._ The contrived example below is the upper bound of what we consider comprehensible code:
104
75
105
76
```go
106
77
funcdoSomething() error {
@@ -134,14 +105,23 @@ func doSomething() error {
134
105
135
106
Note that trivial `if err != nil` branches are discounted here.
136
107
137
-
_We **do not** subscribe to concepts like cyclomatic complexity or lines of
138
-
code, only a simple metric of how nested is business logic in a region of code._
139
-
For non-trivial changes and additions, review your code and consider if it can
140
-
be broken up to promote a [line-of-sight][los] and in turn improve readability.
141
-
To reiterate: long functions are usually fine, wide functions are often not.
142
-
As with most/all rules, there are certainly exceptions to this rule but they
143
-
will be very rare.
108
+
_We **do not** subscribe to concepts like cyclomatic complexity or lines of code, only a simple metric of how nested is business logic in a region of code._ For non-trivial changes and additions, review your code and consider if it can be broken up to promote a [line-of-sight][los] and in turn improve readability. To reiterate: long functions are usually fine, wide functions are often not. As with most/all rules, there are certainly exceptions to this rule but they will be very rare.
Gram is a platform for creating, curating, and hosting MCP servers. Curate and scope toolsets for every use case. Host and secure MCP servers with ease.
32
+
[Gram](https://app.getgram.ai) is a platform for creating, curating, and hosting Model Context Protocol (MCP) servers with ease. We currently support both OpenAPI documents as well as custom TypeScript functions as sources for tools.
33
33
34
34
## What can you do with Gram?
35
35
36
36
With Gram you can empower your LLM and Agents to access the right data at the right time. Gram provides a high-level TypeScript SDK and OpenAPI support to define tools, compose higher order custom tools and group tools together into toolsets. Every toolset is instantly available as a hosted and secure MCP server.
37
37
38
-
If you are looking to get started on the hosted platform you can do that [here](https://app.getgram.ai/) or check out the [quickstart guide](https://www.speakeasy.com/docs/gram/introduction).
38
+
If you are looking to get started on the hosted platform you can [Sign up](https://app.getgram.ai/), or check out the [Quickstart guide](https://www.getgram.ai/docs/introduction).
39
39
40
40
## Features
41
41
@@ -46,22 +46,22 @@ If you are looking to get started on the hosted platform you can do that [here](
46
46
└ First class support for OpenAPI `3.0.X` and `3.1.X`.
47
47
└ Follows the [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) specification.
48
48
49
-
## Getting started with Gram Functions
49
+
## Gram Functions
50
50
51
-
Create agentic tools from simple TypeScript code using the [Gram Functions Framework](https://www.speakeasy.com/docs/gram/gram-functions/introduction). See the getting started [guide](https://www.speakeasy.com/docs/gram/getting-started/typescript) to learn more.
51
+
Create agentic tools from simple TypeScript code using the [Gram Functions Framework](https://www.getgram.ai/docs/gram-functions/introduction). Refer to the [Getting Started](https://www.getgram.ai/docs/getting-started/typescript) guide to learn more.
52
52
53
53
The fastest way to get started is with the `npm create @gram-ai/function@latest` command, which creates a complete TypeScript project with a working Gram function. Deployable and runnable locally as a MCP server.
54
54
55
55
```bash
56
-
# Install the CLI and Create a new project
56
+
# Install the CLI and follow the prompts
57
57
npm create @gram-ai/function@latest
58
58
59
+
# Once created, move into your newly created function directory
60
+
cd my_function
61
+
59
62
# Build and Deploy
60
63
npm run build
61
64
npm run push
62
-
63
-
# Check out your first function
64
-
cd my_function/src/gram.ts
65
65
```
66
66
67
67
A default function is created for you.
@@ -87,7 +87,7 @@ In addition you get a:
87
87
- A `server.ts` is created so you can run the tool locally as a MCP server with MCP inspector with `pnpm run dev`
88
88
- A `README` and `CONTRIBUTING` guide for next steps on building out your custom tool.
89
89
90
-
## Common use cases include:
90
+
###Common use cases include:
91
91
92
92
└ Host one or more remote MCP servers at a custom domain like `mcp.{your-company}.com`.
93
93
└ Power your in-application chat by exposing context from your internal APIs or 3rd Party APIs through tools.
@@ -96,59 +96,32 @@ In addition you get a:
96
96
97
97
Check out the `examples` folder in this repo for working examples. Or open a pull request if you have one to share!
98
98
99
-
## `gram` CLI
100
-
101
-
The `gram` CLI a tool for programmatic access to Gram. Get started with documentation [here](https://docs.getgram.ai/command-line/installation).
102
-
103
-
### Local development
99
+
## Gram CLI
104
100
105
-
Quickstart:
101
+
The CLI allows for programmatic access to Gram, enabling you to manage the process of pushing sources (either OpenAPI documents or Gram Functions) for your MCP servers. Get started with documentation [here](https://www.getgram.ai/docs/command-line).
106
102
107
103
```bash
108
-
cd cli
109
-
go run . --help
104
+
curl -fsSL https://go.getgram.ai/cli.sh | bash
110
105
```
111
106
112
-
### Releases
107
+
And then:
113
108
114
-
> [!NOTE]
115
-
> All CLI updates must follow the [changeset process](./docs/runbooks/version-management-with-changesets.md).
116
-
117
-
New versions of the CLI are released automatically with [GoReleaser](./.goreleaser.yaml).
118
-
119
-
Version bumps are determined by the git commit's prefix:
120
-
121
-
| Prefix | Version bump | Example commit message |
|`feat!:`| Major |`feat!: breaking change to deployments`|
124
-
|`feat:`| Minor |`feat: new status fields`|
125
-
|`fix:`| Patch |`patch: update help docs`|
109
+
```bash
110
+
gram auth
111
+
```
126
112
127
113
## Support
128
114
129
115
- Slack: [Join our slack](https://join.slack.com/t/speakeasy-dev/shared_invite/zt-3hudfoj4y-9EPqMmHIFhNiTtannqiV3Q) for support and discussions
130
116
- In-App: When using the [application](https://app.getgram.ai/) you can engage with the core maintainers of the product.
131
117
- GitHub: Contribute or report issues [on this repository](https://github.com/speakeasy-api/gram/issues/new).
132
-
- Documentation for Gram is also open source. View it [here](https://www.speakeasy.com/docs/gram/introduction) and contribute [here](https://github.com/speakeasy-api/developer-docs/tree/main/docs/gram).
118
+
- Documentation for Gram is also open source. View it [here](https://www.getgram.ai/docs/introduction) and contribute [here](https://github.com/speakeasy-api/developer-docs/tree/main/docs/gram).
133
119
134
120
## Contributing
135
121
136
-
Contributions are welcome! Please open an issue or discussion for questions or suggestions before starting significant work!
137
-
Here's how you can develop on the stack and contribute to the project.
138
-
139
-
### Development
140
-
141
-
Run `./zero` until it succeeds. This script is what you will use to run the dashboard and services for local development. It will also handle installing dependencies and running pending database migrations before starting everything up.
142
-
143
-
The main dependencies for this project are Mise and Docker. The `./zero` script will guide you to install these if they are not found.
144
-
145
-
### Coding guidelines
146
-
147
-
All AI coding guidelines are written out in [CLAUDE.md](./CLAUDE.md). Please make sure you read the [contributing guidelines](./CONTRIBUTING.md) before submitting changes to this project.
148
-
149
-
### Putting up pull requests
122
+
Contributions are welcome! Please open an issue or discussion for questions or suggestions before starting significant work.
150
123
151
-
Please have a good title and description for your PR. Go nuts with streams of commits but invest in a reviewable PR with good context.
124
+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and detailed contribution guidelines.
0 commit comments