feat: add OpenAPI tags for improved SDK generation and API organization

[beshkenadze]

Summary

Adds OpenAPI tags to improve SDK generation and API documentation organization, as discussed in #644.

Changes

• Go Code: Define tag metadata (name + description) in internal/api/router/router.go using Huma's api.OpenAPI().Tags
• Reference Spec: Update docs/reference/api/openapi.yaml to match the generated spec
• Tags Added: servers, publish, auth, admin, health, ping

Benefits

• ✅ Improved SDK generation with proper service grouping (e.g., serversService, publishService)
• ✅ Better API documentation organization in Scalar UI, Swagger UI, and other tools
• ✅ Code-first approach ensures reference spec stays in sync via compliance tests

Testing

• ✅ Compliance test passes: go test -v ./internal/api -run TestOpenAPIEndpointCompliance
• ✅ All 4 reference endpoints verified as implemented
• ✅ TypeScript SDK regenerated successfully with proper tag-based grouping

Related

Closes #644

[beshkenadze]

@rdimitrov Hey!

I’m not sure if manually editing the OpenAPI file is a good idea.

I wrote a small Go script that exports the OpenAPI spec without running the server directly.
Since I’m not very confident in my Go skills and don’t have much experience with it, I’m not sure if it’s worth including.
I can either add it to this PR or submit it as a separate one.

I also added (just for testing) a Scalar UI setup (similar to Swagger UI) and a generated TypeScript SDK.
Scalar UI is quite convenient for testing APIs externally and can be hosted as static files.
If you think it could be useful, I can also submit it in a separate PR.

[rdimitrov]

Thanks for contributing this! 🙏

Overall the approach is good, but I think what's necessary is the changes that are:

• in the router.go (technically speaking the tags are already there, but they lack descriptions, makes sense to have it)
• In the openapi.yaml file these make sense -

tags:
  - name: servers
    description: Operations for discovering and retrieving MCP servers
  - name: publish
    description: Operations for publishing MCP servers to the registry

along with adding them to the corresponding server and publisher endpoints via tags: [servers] and tags: [publish].

I think the rest of the changes in this file are not necessary, i.e. we don't need these tags because we don't have handlers for them in the reference schema (they are implementation specific):

  - name: auth
    description: Authentication and authorization endpoints
  - name: admin
    description: Administrative operations (restricted access)
  - name: health
    description: Health check and system status endpoints
  - name: ping
    description: Simple connectivity test endpoint

[rdimitrov]

Thanks! 🙏