Server Detail should provide a well-defined method to automate server execution

[dmartinol]

The seed data included in the data folder
contains server definitions that can't be automatically executed without accessing the GH repo and reading the README file.

For instance (BTW: no intention to blame anyone, there are many similar examples in the file), this server does not specify the command to run:

  {
    "id": "d86f2098-0be9-4b52-b32e-9d0f17333197",
    "name": "io.github.tinyfish-io/agentql-mcp",
    "description": "Model Context Protocol server that integrates AgentQL's data extraction capabilities.",
    "repository": {
      "url": "https://github.com/tinyfish-io/agentql-mcp",
      "source": "github",
      "id": "906462272"
    },
    "version_detail": {
      "version": "0.0.1-seed",
      "release_date": "2025-05-16T18:56:54Z",
      "is_latest": true
    },
    "packages": [
      {
        "registry_name": "unknown",
        "name": "agentql-mcp",
        "version": "1.0.0",
        "environment_variables": [
          {
            "description": "YOUR_API_KEY",
            "name": "AGENTQL_API_KEY"
          }
        ]
      }
    ]
  },

The recommended server setup from provider's GH repo is:

{
  "mcpServers": {
    "agentql": {
      "command": "npx",
      "args": ["-y", "agentql-mcp"],
      "env": {
        "AGENTQL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Shouldn't the registry specification be more clear on how to execute the server? This way, a registry could really serve to an application to select the desired servers and easily run them.
Maybe, exposing also the server configuration with a Claude-compatible specification would help (not sure this is an MCP standard, it doesn't seem to be mentioned in the protocol specs), WDYT?

[connor4312]

that specific package is bad in the seed data, but please see #33 for how the "Claude-compatible specification" style can be generated from registry entries

[dmartinol]

Let me rephrase it this way: what if I want to automatically scan the server for security vulnerabilities and eventually build the docker image to execute a pre-built, validated server image, instead of fetching the packages on every execution?

The first use case probably needs a Claude-compatible configuration to execute the scanning tool (at least, I see that some of them use this approach): if we need a logic to convert the server definition from the registry to the mcpServers definition, it'd be better to have a reusable conversion function in the registry codebase, or a conversion API exposed for the same reason.

The second case requires us to define the proper installation command for a local tool (e.g., npm install, uvx tool install). To avoid creating a weak system, we should not duplicate the logic for generating these commands or rely on assumptions that may break in the future. For example, the current association for uvx is not robust and could easily fail if its configuration changes: "registry_name": "unknown" and first argument named "uvx" 🤔

[tadasant]

The first use case probably needs a Claude-compatible configuration to execute the scanning tool (at least, I see that some of them use this approach): if we need a logic to convert the server definition from the registry to the mcpServers definition, it'd be better to have a reusable conversion function in the registry codebase, or a conversion API exposed for the same reason.

This is the intent of all the work we are doing to well-define the packages field (example). See #134 if the design is not clear (and I welcome suggestions for making it clearer on those new docs).

We do expect there to be a need for some sort of SDK (either baked into the official MCP ones, or some separate "registry API SDK") to address your latter concern.

But I think we wouldn't bake in opinionation like "build a Claude-compatible JSON" from a registry packages entry until something like this standardized configuration scheme has landed.

For example, the current association for uvx is not robust and could easily fail if its configuration changes: "registry_name": "unknown" and first argument named "uvx" 🤔

Good callout, we shouldn't allow unknown in the code. That should be a strict enum. #136

[dmartinol]

Thanks @tadasant : I will add further comments to Define a Standard MCP Configuration Schema.
My ultimate goal is to identify a clear path to generate a container image executing the server code and, ATM, there are too many assumptions we have to do to clearly define a reliable Dockerfile.