Discovery of UTCP Manuals

[Fannon]

Hi there!

Just looking through the spec, I really like the idea of how it's designed compared to MCP (or complementary).

I have some questions / suggestions about the discovery of UTCP manuals though:

Just calling /utcp is I think not a very scalable approach, because:

• One server can have any number of APIs, also MCP Remote APIs. They might all have different auth mechanisms. So if you start creating UTCP manuals, I assume you have to to it for each existing API. In my company (SAP), some applications may even have hundreds or thousands of APIs, so putting everything into one metadata JSON file would not scale in any way.
• Consider returning a "config" document here, which tells you that UTCP discovery is supported and where to find the individual UTCP manuals. Then you have a more scalable, flexible discovery approach.
• Register a well-known URI location, as this is the RFC standard way to do this, e.g. .well-known/utcp.json or .well-known/universal-tool-calling-protocol.json
• Generally, have you considered returning more than one auth? In practice one API can have any number of auth middlewares and support multiple auth strategies at the same time. Between server and client there is a "strategy pattern": The server implemented auth, so he lists the auth strategies it provides. The client choses one of the auth strategies on its own preferences.
• Consider registering or at least stating the media type for the UTCP manual, then you could reuse the very minimal RFC9727 discovery by giving guidance how to use it.

For examples, see:

• https://datatracker.ietf.org/doc/rfc9727/ (very minimal approach to this)
• https://open-resource-discovery.github.io/specification/spec-v1#ord-configuration-endpoint (this is a spec that I'm responsible for)
• https://help.akana.com/content/current/cm/api_oauth/oauth_discovery/m_oauth_getOpenIdConnectWellknownConfiguration.htm

I'm also a specification author for https://open-resource-discovery.github.io/specification/, which is about decentralized metadata discovery - protocol independent. It's like RFC9727, but more extensive / enterprisy and going beyond just API discovery. I'm considering adding UTCP as one type of metadata supported. If you're interested we could get in touch on this.

Best,
Simon

[h3xxit]

Hi Simon,
Apologies for the late response, I have somehow missed this issue. I would love to get in touch with you, lets set up a call at your earliest convenience. You can reach out to me via my email at https://www.utcp.io/about/about-us

Clarification

• "Just calling /utcp is I think not a very scalable approach, because"
  Correct, /utcp is just an example. But you can serve manuals at any endpoint. UTCP doesnt directly handle the distribution of manuals, so for now, this could look like our registry: https://www.utcp.io/registry (this is for now still outdated to 0.1 unfortunately, work to update to 1.0 in progress)

Where, when a user wants to register a manual, they just copy the json to register it:

{
        "name": "openlibrary",
        "call_template_type": "http",
        "http_method": "GET",
        "url": "https://openlibrary.org/static/openapi.json",
        "content_type": "application/json",
        "auth": null
}

The url here doesnt have to point to /utcp, it can point to anything. And the auth here is only for the discovery endpoint, each tool also has its own Call Template to call it, which includes its own protocol-specific details and its own auth.

Feature ideas

• Creating a new type of doc, which specifies available Manual Call Templates to call to get manuals at .well-known/ is an interesting idea. Its basically a spec for a registry that can be registered automatically. We could make an issue for this and discuss what the general consensus on this is
• I dont know if recursive manuals which include other manuals is a good idea. Its easy to manipulate to add evil tools, so I think the separate registry type approach is probably better
• Supporting multiple auths is also an interesting idea. Not sure how the choice would be made on which to choose, as the AI never sees anything auth related. But it's definitely a good point to bring to the discussion. Perhaps it just chooses the auth it has the credentials for. In that case, its a very good idea

[Fannon]

Dear @h3xxit ,

Ok, I see, then /utcp is not part of the spec but just an example?
I would propose to consider between the concerns between creating a registry (which is basically a collection of all manuals coming from multiple applications) and the need for an application to self-describe the manuals it offers. The self-description is actually useful to automatically publish and update the registry.

But in both cases, the response would have to be an array, as one application could have several manuals, describing several APIs.

I'm pretty sure that having multiple auths is critical, because APIs in the real world have multiple auths at the same time. Consider how this works in OpenAPI, where you can have many different security schemes (but it seems to be limited to one of the same "type", which makes sense to me): https://swagger.io/docs/specification/v3_0/authentication/

[h3xxit]

I would propose to consider between the concerns between creating a registry (which is basically a collection of all manuals coming from multiple applications) and the need for an application to self-describe the manuals it offers. The self-description is actually useful to automatically publish and update the registry.

Yeah so basically put the registry at .well-known/ right?
But yeah, 2 concerns, one to define a registry as a list of manuals. Another is to set a well-known URL at which applications can publicize registries.

I've opened an issue with the multiple auth: #55
If I got the other 2 concerns you raise correctly, then I'll also open some issues with them.

[Fannon]

The registry probably don't need to have a .well-known/ because it's will probably have a dedicated API to get all its content.
But if you can share the same discovery mechanism, you could also reuse .well-known/, if behind that you first discover a list of all manuals which you can then separately download. Otherwise it would not scale for a big registry.

But also considering the scalability of it for big applications (in my company some applications have several hundred or thousands of APIs) makes sense.

Applications do not publish registries, they publish manuals / APIs. Registries will either fetch them or they are pushed / uploaded to the registries

[h3xxit]

Would you be up for a call sometime next week? Would love to understand the issues you're facing and get some of your insights on this discovery. Here's my email: razvan.radulescu@bevel.software