Excited about Apollo and want to make it better? We're excited too!
Apollo is a community of developers just like you, striving to create the best tools and libraries around GraphQL. We welcome anyone who wants to contribute or provide constructive feedback, no matter the age or level of experience. If you want to help but don't know where to start, let us know, and we'll find something for you.
Oh, and if you haven't already, join our community forums.
Here are some ways to contribute to the project, from easiest to most difficult:
This package is an integration layer built on top of Apollo Client. If you encounter an issue that appears to be in the core Apollo Client library rather than the MCP Apps integration, please open an issue or contribute directly in the apollographql/apollo-client repository. See Apollo Client's own CONTRIBUTING.md for guidance on contributing there.
If you're unsure whether an issue belongs here or in the core library, feel free to open an issue here and we'll help triage it.
If you encounter a bug, please file an issue on GitHub via the repository of the sub-project you think contains the bug. If an issue you have is already reported, please add additional information or add a 👍 reaction to indicate your agreement.
While we will try to be as helpful as we can on any issue reported, please include the following to maximize the chances of a quick fix:
- Intended outcome: What you were trying to accomplish when the bug occurred, and as much code as possible related to the source of the problem.
- Actual outcome: A description of what actually happened, including a screenshot or copy-paste of any related error messages, logs, or other output that might be related. Places to look for information include your browser console, server console, and network logs. Please avoid non-specific phrases like "didn't work" or "broke".
- How to reproduce the issue: Instructions for how the issue can be reproduced by a maintainer or contributor. Be as specific as possible, and only mention what is necessary to reproduce the bug. If possible, isolate the exact circumstances in which the bug occurs. Avoid speculation over what the cause might be.
Creating a good reproduction really helps contributors investigate and resolve your issue quickly. In many cases, the act of creating a minimal reproduction illuminates that the source of the bug was somewhere outside the library in question, saving time and effort for everyone.
Improving the documentation, examples, and other open source content can be the easiest way to contribute to the library. If you see a piece of content that can be better, open a PR with an improvement, no matter how small! If you would like to suggest a big change or major rewrite, we'd love to hear your ideas! Please open a feature request for discussion before writing the PR.
In addition to reporting issues, a great way to contribute to Apollo is to respond to other peoples' issues and try to identify the problem or help them work around it. If you're interested in taking a more active role in this process, please go ahead and respond to issues. And don't forget to say "Hi" in our community forums!
This package uses knope to automate its versioning and release process. When contributing, your PR should contain a "changeset" that can be generated by running npm run changeset from your branch locally.
The changeset CLI will ask you to enter the corresponding semver bump type and a short summary of your changes: feel free to enter a brief description via the command line and continue editing the generated Markdown file found inside of .changeset in your editor of choice. When editing your changeset's Markdown file, you can leverage any of the features of GitHub flavored markdown! The description you provide in your changeset will be used to generate an entry in CHANGELOG.md and the release notes in a future release, so the more complete and descriptive the better. Include code samples where necessary.
For a small bug fix change (less than 20 lines of code changed), feel free to open a pull request. We'll try to merge it as fast as possible and ideally publish a new release on the same day. The only requirement is, make sure you also add a test that verifies the bug you are trying to fix.
Most of the features in this package came from suggestions by you, the community! We welcome any ideas about how to make the MCP Apps integration better for your use case. Please open an issue with your details.
This includes:
- Big bug fixes
- New features
For significant changes to a repository, it's important to settle on a design before starting on the implementation. This way, we can make sure that major improvements get the care and attention they deserve. Since big changes can be risky and might not always get merged, it's good to reduce the amount of possible wasted effort by agreeing on an implementation design/plan first.
- Open an issue. Open an issue about your bug or feature request.
- Reach consensus. Some contributors and community members should reach an agreement that this feature or bug is important, and that someone should work on implementing or fixing it.
- Agree on intended behavior. On the issue, reach an agreement about the desired behavior. In the case of a bug fix, it should be clear what it means for the bug to be fixed, and in the case of a feature, it should be clear what it will be like for developers to use the new feature.
- Agree on implementation plan. Write a plan for how this feature or bug fix should be implemented. What modules need to be added or rewritten? Should this be one pull request or multiple incremental improvements? Who is going to do each part?
- Submit PR. In the case where multiple dependent patches need to be made to implement the change, only submit one at a time. Otherwise, the others might get stale while the first is reviewed and merged. Make sure to avoid "while we're here" type changes - if something isn't relevant to the improvement at hand, it should be in a separate PR; this especially includes code style changes of unrelated code.
- Review. At least one core contributor should sign off on the change before it's merged. Look at the "code review" section below to learn about factors are important in the code review. If you want to expedite the code being merged, try to review your own code first!
- Merge and release!
It's important that every piece of code in Apollo packages is reviewed by at least one core contributor familiar with that codebase. Here are some things we look for:
- Required CI checks pass. This is a prerequisite for the review, and it is the PR author's responsibility. As long as the tests don't pass, the PR won't get reviewed.
- Simplicity. Is this the simplest way to achieve the intended goal? If there are too many files, redundant functions, or complex lines of code, suggest a simpler way to do the same thing. In particular, avoid implementing an overly general solution when a simple, small, and pragmatic fix will do.
- Testing. Do the tests ensure this code won't break when other stuff changes around it? When it does break, will the tests added help us identify which part of the library has the problem? Did we cover an appropriate set of edge cases? Look at the test coverage report if there is one. Are all significant code paths in the new code exercised at least once?
- No unnecessary or unrelated changes. PRs shouldn't come with random formatting changes, especially in unrelated parts of the code. If there is some refactoring that needs to be done, it should be in a separate PR from a bug fix or feature, if possible.
- Code has appropriate comments. Code should be commented, or written in a clear "self-documenting" way.
- Idiomatic use of the language. In TypeScript, make sure the typings are specific and correct. In ES2015, make sure to use imports rather than require and const instead of var, etc. Ideally a linter enforces a lot of this, but use your common sense and follow the style of the surrounding code.
Build the package once:
npm run build
Run all tests once:
npm run test
Run all tests in watch mode:
npm run test:watch
It can be useful to test your local changes against a real MCP app. The Apollo AI Apps Template provides a complete setup for this purpose.
From the root of this repository, build the package and create a local .tgz tarball:
npm run build && npm packThis creates a file like apollo-client-ai-apps-0.6.5.tgz in the root of the repo. Note the path to this file — you'll need it in the next step.
Scaffold a new project from the template:
npx tiged apollographql/ai-apps-template mcp-apps-reproduction
cd mcp-apps-reproduction
./install.shIn the template's React app (dev/the-store/package.json), replace the published @apollo/client-ai-apps version with the path to your local .tgz:
{
"dependencies": {
"@apollo/client-ai-apps": "file:/path/to/apollo-client-ai-apps-0.6.5.tgz"
}
}Then reinstall dependencies in that directory:
cd dev/the-store
npm installYou'll need three terminal windows:
Terminal 1 — GraphQL API:
cd ecommerce-graph
npm run devTerminal 2 — React app:
cd dev/the-store
npm run dev:mcpTerminal 3 — MCP server:
./start_mcp.shWhen you make changes to this package:
- Rebuild and repack:
npm run build && npm pack - Reinstall in the template:
cd dev/the-store && npm update @apollo/client-ai-apps - Restart the React app dev server
Refer to the MCP Apps Quickstart Guide for more details on configuring the template, setting up tunneling for end-to-end testing with a host like ChatGPT, and other development workflows.