Add support for Operation Collections #118

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Merged

Jephuff merged 25 commits into main from jeffrey/poll-operation-collections

Jun 11, 2025

Contributor

Jephuff commented Jun 4, 2025 •

edited

Loading

Adds operation collection as an OperationSource. It's currently setup so that it will poll for changes every 30s and will only fetch the fully data for operations that change.

A few TODOs which I can either do in this PR or as fast follows

The first request should be the full operation collection data to avoid running the poll request and then fetching the data
Explorer supports jsonc, should we consider supporting that here as well?

Collaborator

svc-apollo-docs commented Jun 4, 2025 •

edited

Loading

✅ Docs preview has no changes

The preview was not built because there were no changes.

Build ID: f4d9ccb27f26f05820cd16db

Jephuff force-pushed the jeffrey/poll-operation-collections branch from f422991 to f818ae0 Compare

June 4, 2025 18:41

Jephuff marked this pull request as ready for review

June 5, 2025 17:59

Jephuff requested a review from a team as a code owner

June 5, 2025 17:59

Jephuff added 2 commits

June 5, 2025 11:23


          fetch operation collection

ad2118b


          Poll Operation Collections

9bad1a3

Jephuff force-pushed the jeffrey/poll-operation-collections branch from 3972dbe to 9bad1a3 Compare

June 5, 2025 18:24

DaleSeo reviewed

View reviewed changes

crates/apollo-mcp-server/src/operation_collection.rs Outdated Show resolved Hide resolved

crates/apollo-mcp-server/src/operation_collection.rs Outdated

+              }
+              impl CollectionSource {
+                  pub fn into_stream(self) -> Pin<Box<dyn Stream<Item = CollectionEvent> + Send>> {

Contributor

DaleSeo Jun 5, 2025

This return type looks Greek to me 😂

crates/apollo-mcp-server/src/operation_collection.rs Outdated Show resolved Hide resolved

crates/apollo-mcp-server/src/operation_collection.rs Outdated Show resolved Hide resolved

crates/apollo-mcp-server/src/operation_collection.rs Outdated Show resolved Hide resolved

crates/apollo-mcp-server/src/operation_collection.rs Outdated Show resolved Hide resolved

crates/apollo-mcp-server/src/operation_collection.rs Outdated Show resolved Hide resolved

crates/apollo-mcp-server/src/operation_collection.rs Outdated

+                                  operation.id.clone(),
+                                  CollectionData {
+                                      last_updated_at: updated_at,
+                                      raw_operation: None,

Contributor

DaleSeo Jun 5, 2025

Why are we setting this to None? Shouldn't we set it to the updated operation?

Contributor Author

Jephuff Jun 5, 2025

We don't have the operation data yet at this point because we've only run the poll query.

But thinking about it, writing to this cache would only really help if we have overlapping requests and we probably should avoid that. So maybe we could make raw operations required and write to the cache once we get the full body back 🤔

crates/apollo-mcp-server/src/operation_collection.rs Outdated Show resolved Hide resolved

DaleSeo reviewed

View reviewed changes

crates/apollo-mcp-server/src/operation_collection.rs Outdated Show resolved Hide resolved

pubmodmatt reviewed

View reviewed changes

Contributor

pubmodmatt left a comment

I'll have more commets, but I'm suggesting some things that have a wide impact so getting these out first

crates/apollo-mcp-server/src/operation_collection.rs Outdated Show resolved Hide resolved

crates/apollo-mcp-server/src/operation_collection.rs Outdated Show resolved Hide resolved

pubmodmatt reviewed

View reviewed changes

crates/apollo-mcp-server/src/platform-api.graphql Outdated Show resolved Hide resolved

DaleSeo reviewed

View reviewed changes

crates/apollo-mcp-server/src/main.rs Outdated Show resolved Hide resolved

DaleSeo reviewed

View reviewed changes

crates/apollo-mcp-server/src/event.rs Outdated Show resolved Hide resolved

DaleSeo reviewed

View reviewed changes

crates/apollo-mcp-server/src/platform-api.graphql Outdated Show resolved Hide resolved

DaleSeo approved these changes

View reviewed changes

Contributor

DaleSeo left a comment

Sorry @Jephuff for showering your PR with newbie comments! I was just using it as my Rust crash course. 🙈 Learned heaps, though, so thanks for putting up with my noise!

Now that I’ve wrapped my head around the code, I'll spend some time tomorrow testing it with a graph on Studio.

DaleSeo self-requested a review

June 5, 2025 20:11

Contributor Author

Jephuff commented Jun 5, 2025

Sorry @Jephuff for showering your PR with newbie comments! I was just using it as my Rust crash course. 🙈 Learned heaps, though, so thanks for putting up with my noise!

Now that I’ve wrapped my head around the code, I'll spend some time tomorrow testing it with a graph on Studio.

Love the comments! keep the noise coming, we will learn together :D hahaha

Contributor

DaleSeo commented Jun 6, 2025

@Jephuff I had no luck getting this work locally 😞 The server crashes with Error in response: Not Authorized when I use ---collection option though APOLLO_KEY is set. Am I missing anything?

$ APOLLO_GRAPH_REF=🔑 APOLLO_KEY=🔑 cargo run -p apollo-mcp-server -- -i -u --http-address 127.0.0.1 --http-port 5000 --collection 4efe3d61-a3cf-4906-bd6d-6cdf6c18239b -l debug 
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.16s
     Running `target/debug/apollo-mcp-server -i -u --http-address 127.0.0.1 --http-port 5000 -l debug --collection 4efe3d61-a3cf-4906-bd6d-6cdf6c18239b`
2025-06-06T16:24:08.383024Z  INFO Apollo MCP Server v0.3.0 // (c) Apollo Graph, Inc. // Licensed as ELv2 (https://go.apollo.dev/elv2)
2025-06-06T16:24:08.386057Z DEBUG starting new connection: https://uplink.api.apollographql.com/    
2025-06-06T16:24:08.386799Z DEBUG starting new connection: https://graphql.api.apollographql.com/    
2025-06-06T16:24:08.485455Z DEBUG connecting to 34.30.93.119:443
2025-06-06T16:24:08.485628Z DEBUG connecting to 34.117.186.194:443
2025-06-06T16:24:08.534777Z DEBUG connected to 34.117.186.194:443
2025-06-06T16:24:08.558533Z DEBUG connected to 34.30.93.119:443
2025-06-06T16:24:08.809370Z DEBUG uplink response Response { url: "https://uplink.api.apollographql.com/", status: 200, headers: {"content-type": "application/json;charset=utf-8", "x-cloud-trace-context": "27bd18f8775451310924e30b1eb5b6c4", "date": "Fri, 06 Jun 2025 16:24:08 GMT", "server": "Google Frontend", "content-length": "4338", "via": "1.1 google", "alt-svc": "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000"} }
2025-06-06T16:24:08.814416Z DEBUG pooling idle connection for ("https", uplink.api.apollographql.com)
2025-06-06T16:24:08.833726Z DEBUG Received schema: ✂️(The schema is too long to paste here)✂️

2025-06-06T16:24:08.868704Z DEBUG pooling idle connection for ("https", graphql.api.apollographql.com)
Error: Failed to create operation: Error loading collection: Error in response: Not Authorized

Caused by:
    Error loading collection: Error in response: Not Authorized

Contributor Author

Jephuff commented Jun 6, 2025

@DaleSeo How did you get the APOLLO_KEY? Is it a graph key?

Contributor

DaleSeo commented Jun 6, 2025 •

edited

Loading

@Jephuff Yes, it's a graph key from a graph on my free account. The log indicates that it fetched the schema without any issues using the key.

Contributor Author

Jephuff commented Jun 6, 2025

It looks like you grabbed a personal collection id instead of a shared one. Personal ones would require a user token, but the shared ones would be able to be fetched by the graph token! :)


          Merge remote-tracking branch 'origin/main' into jeffrey/poll-operatio…

fd95e9c

…n-collections

Contributor

DaleSeo commented Jun 9, 2025 •

edited

Loading

It looks like you grabbed a personal collection id instead of a shared one. Personal ones would require a user token, but the shared ones would be able to be fetched by the graph token! :)

Thanks @Jephuff for clarification. I never thought using a personal collection versus a shared collection could make a difference.

I tried using a user key instead, but it fails to fetch the schema from Uplink. 🙃
It seems like I can't use a personal collection unless we introduce a new environment variable. 😞

2025-06-09T13:02:20.456238Z ERROR uplink error, the request will not be retried: code=AUTHENTICATION_FAILED message=Only graph tokens can be used with uplink. User tokens are not supported at this time.
Error: No valid schema was supplied

Contributor

DaleSeo commented Jun 9, 2025

I got it working using a shared collection and a graph key! 🎉

DaleSeo approved these changes

View reviewed changes

Jephuff added 5 commits

June 9, 2025 10:44


          move code to registry

fa64966


          rename studio api to platform api

42071ef


          rename and remove clone

294caf5


          rename query

f125050


          more renames

3df0778

Jephuff added 2 commits

June 9, 2025 16:48


          remove trait

035217f


          feedback

a43018f

Contributor

pubmodmatt commented Jun 10, 2025

Also this definitely needs a changeset entry and doc updates.

Jephuff added 2 commits

June 10, 2025 09:41


          dry pass 1, add request builder helper

18b143c


          dry pass 2

b15404c

apollographql deleted a comment from apollo-librarian bot

apollographql deleted a comment from apollo-librarian bot

Jephuff added 4 commits

June 10, 2025 13:31


          stop polling if collection has over 100 operations

a858fda


          add graphos to words

d2d6b7a


          change some noisy logs to debug

651eddd


          add —collection to reference

fb023fb

Jephuff requested a review from a team as a code owner

June 10, 2025 20:32

apollo-librarian bot commented Jun 10, 2025 •

edited

Loading

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 3 changed, 0 removed

* (developer-tools)/apollo-mcp-server/(latest)/command-reference.mdx
* (developer-tools)/apollo-mcp-server/(latest)/guides/index.mdx
* graphos/routing/(latest)/security/jwt.mdx

Build ID: 64a588ec763284706af03b49

URL: https://www.apollographql.com/docs/deploy-preview/64a588ec763284706af03b49


          add changeset

854a2a4

Jephuff requested a review from pubmodmatt

June 10, 2025 20:40

Jephuff added 2 commits

June 10, 2025 13:42


          undo graphql_client change

9d6faae


          Request all data on first request

92b5f06

apollo-librarian bot reviewed

View reviewed changes

apollo-librarian bot left a comment

AI Style Review Summary

⚠️ This review and suggested changes are AI-generated. Please use common sense when accepting these suggestions, as they may not always be accurate or appropriate for your specific context.

Summary of changes:

The term 'ID' (without code font) is now used when referring generically to an identifier.

The pull request has 1 style issue. Please review the changes and make the necessary adjustments.

If you encounter any issues with this AI review, please reach out to Developer Experience Marketing for assistance.

docs/source/command-reference.mdx Outdated

@@ @@ -109,6 +109,7 @@ apollo-mcp-server [OPTIONS] --directory <DIRECTORY> @@
               | `-x, --explorer`                                      | Expose a tool that returns the URL to open a GraphQL operation in Apollo Explorer (requires `APOLLO_KEY` and `APOLLO_GRAPH_REF`).                                                                                                    |
               | `-o, --operations [<OPERATIONS>...]`                  | Operation files to expose as MCP tools. [Learn more](/apollo-mcp-server/guides/#from-operation-files).                                                                                                                               |
               | `--manifest <MANIFEST>`                               | The path to the persisted query manifest containing operations.                                                                                                                                                                      |
+              | `--collection <COLLECTION_ID>`                        | The id of an operation collection to use as the source for operations                                                                                                                                                                |

apollo-librarian bot Jun 10, 2025

⚠️ Warning

Use 'ID' (no code font) when referring generically to something's identifier.

Suggested change

      
            | `--collection <COLLECTION_ID>`                        | The id of an operation collection to use as the source for operations                                                                                                                                                                |
          
            | <code>--collection <COLLECTION_ID></code>                        | The ID of an operation collection to use as the source for operations                                                                                                                                                                |

Member

BlenderDude Jun 10, 2025

Ignore this for now 😄 working to resolve this issue with the prompt

Contributor Author

Jephuff Jun 10, 2025

Any chance we can turn these off if they aren't quite ready? It's quite a lot and contradicting itself 😂

Contributor

pubmodmatt Jun 11, 2025

I actually agree with the ID capitalization.

Contributor Author

Jephuff Jun 11, 2025

yeah the ID I definitely agree with :)


          bit of cleanup

fc642eb

apollo-librarian bot reviewed

View reviewed changes

apollo-librarian bot left a comment

AI Style Review (Review 1 of 1)

⚠️ This review and suggested changes are AI-generated. Please use common sense when accepting these suggestions, as they may not always be accurate or appropriate for your specific context.

Summary of changes:

Documentation changes include: updating references to 'ID' for generic identifiers, 'id' for GraphQL field names, and 'ID' for the GraphQL scalar type; and clarifying command option descriptions to explicitly state their function, aligning similar options (e.g., --collection) with consistent functional descriptions rather than cross-referencing.

The pull request has 2 style issues. Please review the changes and make the necessary adjustments.

If you encounter any issues with this AI review, please reach out to Developer Experience Marketing for assistance.

docs/source/command-reference.mdx Outdated Show resolved Hide resolved

docs/source/command-reference.mdx Show resolved Hide resolved


          a few renames

c64de16

apollo-librarian bot reviewed

View reviewed changes

apollo-librarian bot left a comment

AI Style Review (Review 1 of 1)

⚠️ This review and suggested changes are AI-generated. Please use common sense when accepting these suggestions, as they may not always be accurate or appropriate for your specific context.

Summary of changes:

Documentation updates include standardizing 'ID' to uppercase for generic identifiers and clarifying command relationships, such as aliasing between '--mcp-collection' and '--collection'.

The pull request has 1 style issue. Please review the changes and make the necessary adjustments.

If you encounter any issues with this AI review, please reach out to Developer Experience Marketing for assistance.

docs/source/command-reference.mdx Show resolved Hide resolved

pubmodmatt reviewed

View reviewed changes

.changesets/feat_jeffrey_poll_operation_collections.md

		@@ -0,0 +1,3 @@
		### Add `--collection <COLLECTION_ID>` as another option for operation source

		Use operation collections as the source of operations for your MCP server. The server will watch for changes and automatically update when you change your operation collection.

Contributor

pubmodmatt Jun 10, 2025

Suggested change

      
            Use operation collections as the source of operations for your MCP server. The server will watch for changes and automatically update when you change your operation collection.
          
            Use shared operation collections as the source of operations for your MCP server. The server will watch for changes and automatically update when you change your operation collection.

Contributor Author

Jephuff Jun 11, 2025

I'm not sure how to word this, you 100% can use a sandbox or personal collection as long as your APOLLO_KEY has access to it. If you do, it is incompatible with uplink but you can still pass in a schema.

Contributor

pubmodmatt Jun 11, 2025

I think we need a larger doc section, beyond just the options in the command reference, that explains this. This will be an immediate area of confusion. But that can be in a follow-on doc PR.

docs/source/command-reference.mdx Outdated

@@ @@ -109,6 +109,7 @@ apollo-mcp-server [OPTIONS] --directory <DIRECTORY> @@
               | `-x, --explorer`                                      | Expose a tool that returns the URL to open a GraphQL operation in Apollo Explorer (requires `APOLLO_KEY` and `APOLLO_GRAPH_REF`).                                                                                                    |
               | `-o, --operations [<OPERATIONS>...]`                  | Operation files to expose as MCP tools. [Learn more](/apollo-mcp-server/guides/#from-operation-files).                                                                                                                               |
               | `--manifest <MANIFEST>`                               | The path to the persisted query manifest containing operations.                                                                                                                                                                      |
+              | `--collection <COLLECTION_ID>`                        | The id of an operation collection to use as the source for operations                                                                                                                                                                |

Contributor

pubmodmatt Jun 11, 2025

I actually agree with the ID capitalization.


          Update docs/source/command-reference.mdx

fc2b7ba

Co-authored-by: apollo-librarian[bot] <212934294+apollo-librarian[bot]@users.noreply.github.com>

Jephuff requested a review from pubmodmatt

June 11, 2025 17:59

Jephuff added 2 commits

June 11, 2025 15:02


          Merge remote-tracking branch 'origin/main' into jeffrey/poll-operatio…

1d42973

…n-collections


          and another info to debug

7797efe

pubmodmatt approved these changes

View reviewed changes

Contributor

pubmodmatt left a comment

Approved, but identified a few things to follow up.

.changesets/feat_jeffrey_poll_operation_collections.md

		@@ -0,0 +1,3 @@
		### Add `--collection <COLLECTION_ID>` as another option for operation source

		Use operation collections as the source of operations for your MCP server. The server will watch for changes and automatically update when you change your operation collection.

Contributor

pubmodmatt Jun 11, 2025

I think we need a larger doc section, beyond just the options in the command reference, that explains this. This will be an immediate area of confusion. But that can be in a follow-on doc PR.

...p-registry/src/platform_api/operation_collections/operation_collection_polling_query.graphql Outdated

Comment on lines 4 to 8

+                      ... on OperationCollection {
+                          operations {
+                              lastUpdatedAt
+                              id
+                          }

Contributor

pubmodmatt Jun 11, 2025

We can work this out after this PR, but I think it's probably both. It may depend on how we integrate this with GraphOS generally - if it's a special MCP collection, maybe that collection simply can't be updated past the limit, for example.

crates/apollo-mcp-registry/src/platform_api/operation_collections/collection_poller.rs Outdated

+                  }
+              }
+              async fn poll_operation_collection(

Contributor

pubmodmatt Jun 11, 2025

This was discussed separately - it sounds like we have some ideas here, but I'd like to see some follow up after this merges.

Jephuff merged commit 5198357 into main

7 checks passed

DaleSeo mentioned this pull request

release: v0.4.0 #143

Merged

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet