refactor: rename icon field to logo and require URL-only values (#118)

* refactor: rename `icon` field to `logo` and require URL-only values

The server-definition `icon` field has long accepted both emoji and URLs,
which made icon rendering ambiguous in the registry UI (the discover site
showed raw emoji where a product logo was intended). This PR:

- Renames `icon` to `logo` in every server definition and example, and
  replaces the seven remaining emoji icons (🛡 mcpshield, 🐛 sentry x3,
  ⚡ supabase x2, 🪞 vardoger) with real logo URLs sourced from GitHub
  org avatars.
- Updates the JSON schema to accept `logo` as `format: uri` with an
  `^https?://` pattern, and keeps `icon` as a deprecated alias with the
  same URL constraint (no more emoji). Emits helpful messages so
  contributors understand which field to use.
- Adds schema-validation tests that reject emoji in both `icon` and
  `logo`, assert every server file uses `logo` (not `icon`), and assert
  every `logo` is an HTTP(S) URL.
- Updates contributor docs — CONTRIBUTING, AGENTS, README, the PR
  template, and the examples README — plus the `mcp-server-crawler`
  skill that agents use to draft new definitions.

This is the source-of-truth rename; the bundler, registry API, and
discover UI land separate PRs that mirror both fields on output so the
desktop app (which still reads `icon`) keeps working.

Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>

* docs(examples): replace emoji in example definitions with real logo URLs

The rename made emoji invalid under the URL-only `logo` schema, so the
example server definitions would not validate. Use the matching GitHub
organisation avatars for each example's real-world service (GitHub,
Atlassian, Cloudflare, Notion) so copy-paste templates pass validation
out of the box.

Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>

---------

Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>

Author: its-mash

.github/PULL_REQUEST_TEMPLATE.md

@@ -70,7 +70,7 @@ CONTRIBUTING.md → "Platform-Managed Fields (Do Not Set)".
 <!-- See CONTRIBUTING.md → "Trademark & Branding Policy" for details. -->
 
 - [ ] No "official" / "certified" / "endorsed" wording unless I represent the trademark owner
-- [ ] I have the right to reference the `icon` URL (emoji or an asset I'm allowed to hot-link)
+- [ ] I have the right to reference the `logo` URL (an asset I'm allowed to hot-link — emoji are not accepted)
 
 ### Tested locally (recommended for new servers)
 

AGENTS.md

@@ -90,7 +90,7 @@ These are computed or granted by McpMux maintainers after verification.
 ## Trademark & Branding
 
 - Reference third-party products with "works with", "for", or "connects to" — never "official", "certified", "endorsed" unless you represent the trademark owner and are verified.
-- Icons are referenced by URL (emoji or external) — McpMux does not host icon files. Only link to assets you have the right to reference.
+- Logos are referenced by HTTP(S) URL in the `logo` field — McpMux does not host logo files and emoji are not accepted. Only link to assets you have the right to reference. The legacy field name `icon` is still accepted for backward compatibility.
 - See `TRADEMARK-TAKEDOWN.md` for the full IP policy.
 
 ## Commit & PR Guidelines

CONTRIBUTING.md

@@ -149,7 +149,7 @@ Strongly encouraged — the registry UI shows them prominently and users filter
 | `$schema` | string | `"../schemas/server-definition.schema.json"` — gives editors autocomplete. |
 | `description` | string | One sentence, plain English. Shown in listings. |
 | `alias` | string | Short CLI alias, pattern `^[a-z0-9-]+$`. Must not collide with any `id` or other alias. |
-| `icon` | string | Emoji (e.g. `"🐙"`) or a stable image URL (avatars, project logos). McpMux does **not** host icon files. |
+| `logo` | string | Stable HTTP(S) URL to a logo image (avatar or project PNG/SVG). Emoji are **not** accepted — use a GitHub avatar URL like `https://avatars.githubusercontent.com/u/{id}?v=4`. McpMux does **not** host logo files. (The legacy field name `icon` is still accepted for backward compatibility, but `logo` is the preferred name.) |
 | `schema_version` | string | Currently `"2.1"`. Bump when the project publishes a new contributor schema version. |
 | `categories` | string[] | IDs from [`categories.json`](categories.json). At least one. |
 | `tags` | string[] | Lowercase keywords for search (`"git"`, `"search"`, `"wiki"`). 3–8 is a good target. |
@@ -582,11 +582,12 @@ The registry is community-built but consumed via the McpMux brand, so we're care
 - **Implied endorsement is not:** "Official GitHub MCP", "Certified by Notion", "Endorsed by Linear" — unless you actually represent the trademark owner and have been verified.
 - Phrases to prefer: *works with*, *for*, *connects to*, *integrates with*.
 
-### Icons
+### Logos
 
-- McpMux does not host icon files. The `icon` field is either an emoji or a URL to an image.
+- McpMux does not host logo files. The `logo` field must be an HTTP(S) URL to an image. Emoji are not accepted.
 - **Only reference assets you have the right to use.** Corporate logos are usually fine for descriptive, non-commercial use in a directory listing; but don't hot-link assets with restrictive terms.
 - Prefer GitHub avatars (`https://avatars.githubusercontent.com/u/<id>?v=4`) or official brand URLs over random CDN copies that may rotate.
+- The legacy field name `icon` is still accepted for backward compatibility, but new submissions should use `logo`.
 
 ### Official / verified claims
 
@@ -603,7 +604,7 @@ By opening a PR you agree that:
 1. You have the right to reference any URLs you include.
 2. You're not claiming official status or endorsement you don't have.
 3. You accept responsibility for trademark compliance of your submission.
-4. You grant McpMux a license to display your definition — including rendering any referenced icon URLs — on the discover site and desktop app.
+4. You grant McpMux a license to display your definition — including rendering any referenced logo URLs — on the discover site and desktop app.
 5. McpMux may modify or remove your submission in response to trademark concerns.
 
 ---

README.md

@@ -92,7 +92,7 @@ Every definition must include these three fields:
   "$schema": "../schemas/server-definition.schema.json",
   "description": "What the server does in one sentence",
   "alias": "my-srv",             // short CLI alias (lowercase kebab-case)
-  "icon": "https://...",         // emoji or image URL
+  "logo": "https://...",         // HTTP(S) URL to a logo image (emoji not accepted)
   "schema_version": "2.1",
   "categories": ["developer-tools"],
   "tags": ["keyword1", "keyword2"],
@@ -368,7 +368,7 @@ Edit the existing JSON file in `servers/` and submit a PR. The same validation r
 ## Trademark & Branding Policy
 
 - **Names:** You may reference third-party products (e.g., "MCP Server for GitHub"). Use language like "works with", "for", or "connects to".
-- **Icons:** Emoji or external URLs only — McpMux does not host icon files. Only reference assets you have the right to use.
+- **Logos:** HTTP(S) URLs only — McpMux does not host logo files and emoji are not accepted. Only reference assets you have the right to use.
 - **Official claims:** Do NOT use "official", "certified", or "endorsed" unless you represent the trademark owner and have been verified by McpMux.
 
 See [TRADEMARK-TAKEDOWN.md](TRADEMARK-TAKEDOWN.md) for the full IP policy.
@@ -397,7 +397,7 @@ pnpm build                       # Generate bundle/bundle.json
   "name": "Brave Search",
   "alias": "brave",
   "description": "Search the web using the Brave Search API with privacy-focused results.",
-  "icon": "https://avatars.githubusercontent.com/u/12301619?v=4",
+  "logo": "https://avatars.githubusercontent.com/u/12301619?v=4",
   "schema_version": "2.1",
   "categories": ["search"],
   "tags": ["brave", "search", "web-search", "privacy"],
@@ -466,7 +466,7 @@ pnpm build                       # Generate bundle/bundle.json
   "name": "Cloudflare Docs",
   "alias": "cf-docs",
   "description": "Search Cloudflare developer documentation using semantic search.",
-  "icon": "https://avatars.githubusercontent.com/u/314135?v=4",
+  "logo": "https://avatars.githubusercontent.com/u/314135?v=4",
   "schema_version": "2.1",
   "categories": ["documentation", "cloud"],
   "tags": ["cloudflare", "docs", "workers", "pages"],

examples/README.md

@@ -88,7 +88,7 @@ Key features:
 
 ### Recommended Fields
 - `description` - What the server does
-- `icon` - Emoji or image URL
+- `logo` - HTTP(S) URL to a logo image (PNG/SVG). Emoji are not accepted. Legacy `icon` field name is still supported.
 - `categories` - For discoverability
 - `badges` - Trust indicators (official, verified, featured, sponsored, popular)
 - `hosting_type` - local, remote, or hybrid
@@ -143,10 +143,11 @@ Key features:
 
 ## Best Practices
 
-### Icons
-- Use emoji (📊, 🚀, 📖) for simplicity
-- Or provide URL to PNG/SVG icon
+### Logos
+- Provide an HTTP(S) URL to a PNG/SVG logo — emoji are not accepted
+- Prefer GitHub avatars (`https://avatars.githubusercontent.com/u/<id>?v=4`) or official brand URLs
 - Recommended size: 128x128px or 256x256px
+- The field name is `logo`; the legacy `icon` field name is still supported but discouraged
 
 ### Screenshots
 - Max 5 screenshots

examples/complete-example.json

@@ -4,16 +4,27 @@
   "name": "GitHub",
   "alias": "gh",
   "description": "Interact with GitHub repositories, issues, pull requests, and more through the GitHub API.",
-  "icon": "🐙",
+  "logo": "https://avatars.githubusercontent.com/u/9919?v=4",
   "schema_version": "2.1",
-  "categories": ["developer-tools", "version-control"],
-  "tags": ["git", "code", "issues", "pr", "repos"],
-
+  "categories": [
+    "developer-tools",
+    "version-control"
+  ],
+  "tags": [
+    "git",
+    "code",
+    "issues",
+    "pr",
+    "repos"
+  ],
   "transport": {
     "type": "stdio",
     "command": "docker",
     "args": [
-      "run", "-i", "--rm", "-e",
+      "run",
+      "-i",
+      "--rm",
+      "-e",
       "GITHUB_PERSONAL_ACCESS_TOKEN",
       "ghcr.io/github/github-mcp-server"
     ],
@@ -39,25 +50,22 @@
       ]
     }
   },
-
   "auth": {
     "type": "api_key",
     "instructions": "Create a token at https://github.com/settings/tokens with repo scope"
   },
-
   "contributor": {
     "name": "Model Context Protocol",
     "github": "modelcontextprotocol",
     "url": "https://modelcontextprotocol.io"
   },
-
   "links": {
     "repository": "https://github.com/modelcontextprotocol/servers",
     "documentation": "https://modelcontextprotocol.io/docs"
   },
-
-  "platforms": ["all"],
-
+  "platforms": [
+    "all"
+  ],
   "capabilities": {
     "tools": true,
     "resources": true,

examples/read-only-example.json

@@ -4,36 +4,40 @@
   "name": "Cloudflare Docs",
   "alias": "cfdocs",
   "description": "Search and browse Cloudflare documentation",
-  "icon": "📚",
+  "logo": "https://avatars.githubusercontent.com/u/314135?v=4",
   "schema_version": "2.1",
-  "categories": ["documentation", "cloud"],
-  "tags": ["cloudflare", "docs", "documentation", "search"],
-
+  "categories": [
+    "documentation",
+    "cloud"
+  ],
+  "tags": [
+    "cloudflare",
+    "docs",
+    "documentation",
+    "search"
+  ],
   "transport": {
     "type": "http",
     "url": "https://docs.mcp.cloudflare.com/mcp",
     "metadata": {
       "inputs": []
     }
   },
-
   "auth": {
     "type": "none"
   },
-
   "contributor": {
     "name": "Cloudflare",
     "github": "cloudflare",
     "url": "https://developers.cloudflare.com"
   },
-
   "links": {
     "repository": "https://github.com/cloudflare/mcp-server-cloudflare",
     "documentation": "https://developers.cloudflare.com/mcp"
   },
-
-  "platforms": ["all"],
-
+  "platforms": [
+    "all"
+  ],
   "capabilities": {
     "tools": true,
     "resources": true,

examples/remote-hosted-example.json

@@ -4,36 +4,41 @@
   "name": "Atlassian (Jira & Confluence)",
   "alias": "atlassian",
   "description": "Interact with Jira issues and Confluence pages",
-  "icon": "🔷",
+  "logo": "https://avatars.githubusercontent.com/u/168166?v=4",
   "schema_version": "2.1",
-  "categories": ["productivity", "developer-tools"],
-  "tags": ["jira", "confluence", "atlassian", "issues", "wiki"],
-
+  "categories": [
+    "productivity",
+    "developer-tools"
+  ],
+  "tags": [
+    "jira",
+    "confluence",
+    "atlassian",
+    "issues",
+    "wiki"
+  ],
   "transport": {
     "type": "http",
     "url": "https://mcp.atlassian.com/v1/mcp",
     "metadata": {
       "inputs": []
     }
   },
-
   "auth": {
     "type": "oauth"
   },
-
   "contributor": {
     "name": "Atlassian",
     "github": "atlassian",
     "url": "https://developer.atlassian.com"
   },
-
   "links": {
     "homepage": "https://developer.atlassian.com/cloud/mcp",
     "documentation": "https://developer.atlassian.com/cloud/mcp/docs"
   },
-
-  "platforms": ["all"],
-
+  "platforms": [
+    "all"
+  ],
   "capabilities": {
     "tools": true,
     "prompts": true,

examples/sponsored-example.json

@@ -4,15 +4,25 @@
   "name": "Notion",
   "alias": "notion",
   "description": "Read and write Notion pages, databases, and blocks",
-  "icon": "📝",
+  "logo": "https://avatars.githubusercontent.com/u/4792552?v=4",
   "schema_version": "2.1",
-  "categories": ["productivity", "documentation"],
-  "tags": ["notion", "notes", "wiki", "database"],
-
+  "categories": [
+    "productivity",
+    "documentation"
+  ],
+  "tags": [
+    "notion",
+    "notes",
+    "wiki",
+    "database"
+  ],
   "transport": {
     "type": "stdio",
     "command": "npx",
-    "args": ["-y", "@notionhq/notion-mcp-server"],
+    "args": [
+      "-y",
+      "@notionhq/notion-mcp-server"
+    ],
     "env": {
       "NOTION_API_KEY": "${input:NOTION_API_KEY}"
     },
@@ -35,25 +45,22 @@
       ]
     }
   },
-
   "auth": {
     "type": "api_key",
     "instructions": "Create an integration at notion.so/my-integrations"
   },
-
   "contributor": {
     "name": "Notion",
     "github": "makenotion",
     "url": "https://notion.so"
   },
-
   "links": {
     "repository": "https://github.com/makenotion/notion-mcp-server",
     "documentation": "https://developers.notion.com"
   },
-
-  "platforms": ["all"],
-
+  "platforms": [
+    "all"
+  ],
   "capabilities": {
     "tools": true,
     "resources": true,

schemas/server-definition.schema.json

@@ -25,9 +25,18 @@
       "type": "string",
       "description": "Short description of what the server does"
     },
+    "logo": {
+      "type": "string",
+      "format": "uri",
+      "pattern": "^https?://",
+      "description": "URL to a logo image (PNG/SVG). Must be an HTTP(S) URL - emoji are no longer accepted. Prefer a GitHub avatar (https://avatars.githubusercontent.com/u/{id}?v=4) or a stable brand asset."
+    },
     "icon": {
       "type": "string",
-      "description": "Emoji or URL to icon image"
+      "format": "uri",
+      "pattern": "^https?://",
+      "deprecated": true,
+      "description": "Deprecated: use `logo` instead. Kept for backward compatibility with older bundles; when present it must be an HTTP(S) URL."
     },
     "schema_version": {
       "type": "string",