docs: expand contributor docs and restructure issue templates

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,56 @@
+name: Bug in a Server Definition
+description: Report a problem with an existing server definition in the registry
+title: "[Bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this to report a broken or incorrect server definition already in the registry.
+
+        Bugs in the McpMux desktop app itself belong in the [mcp-mux repo](https://github.com/mcpmux/mcp-mux/issues/new/choose).
+
+  - type: input
+    id: server_id
+    attributes:
+      label: Server ID
+      description: The `id` field from the JSON definition (e.g., `community.brave-search`).
+      placeholder: community.example-server
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What's wrong?
+      description: Broken command, missing field, wrong URL, bad `obtain` instructions, etc.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: How can a maintainer confirm the problem?
+      placeholder: |
+        1. Install server `community.example-server` in McpMux
+        2. Attempt to call tool `...`
+        3. Observe error `...`
+    validations:
+      required: false
+
+  - type: input
+    id: mcpmux_version
+    attributes:
+      label: McpMux Version (if applicable)
+      placeholder: e.g., 0.3.0
+    validations:
+      required: false
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Screenshots
+      description: Paste any relevant log output, error messages, or screenshots.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Contributing Guide (Pull Request path)
+    url: https://github.com/mcpmux/mcp-servers/blob/main/CONTRIBUTING.md
+    about: The fastest way to add a server — five-command quickstart for opening a PR
+  - name: Questions & Help
+    url: https://github.com/mcpmux/mcp-mux/discussions/categories/q-a
+    about: Ask questions about the registry or McpMux in GitHub Discussions
+  - name: Browse Existing Servers
+    url: https://mcpmux.com
+    about: Search the registry at mcpmux.com before opening a request

.github/ISSUE_TEMPLATE/request-server.yml

@@ -0,0 +1,75 @@
+name: Request a Server
+description: Suggest an MCP server we should add to the registry
+title: "[Request] "
+labels: ["server-request"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Know of an MCP server that should be in the McpMux registry? Tell us about it here.
+
+        If you already have a working definition, use the **Submit a Server** template (or open a PR) instead — that's the fastest path.
+
+  - type: input
+    id: name
+    attributes:
+      label: Server Name
+      description: What is this server called?
+      placeholder: e.g., Linear, Stripe, Obsidian
+    validations:
+      required: true
+
+  - type: input
+    id: repository
+    attributes:
+      label: Upstream Repository or Homepage
+      description: Link to the MCP server's source code or docs (leave blank if you don't know of one yet)
+      placeholder: https://github.com/... or https://example.com/mcp
+    validations:
+      required: false
+
+  - type: textarea
+    id: use_case
+    attributes:
+      label: What would you use it for?
+      description: A concrete example helps us prioritise.
+      placeholder: e.g., "Let Claude read my Linear issues so I can triage from chat."
+    validations:
+      required: true
+
+  - type: dropdown
+    id: transport
+    attributes:
+      label: Transport (if known)
+      options:
+        - Not sure
+        - stdio (local command)
+        - http (remote URL)
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: categories
+    attributes:
+      label: Categories (pick any that fit)
+      options:
+        - label: Developer Tools
+        - label: Version Control
+        - label: Cloud Services
+        - label: Productivity
+        - label: Database
+        - label: Search & Web
+        - label: Communication
+        - label: File System
+        - label: Documentation
+        - label: AI & Machine Learning
+        - label: Monitoring & Observability
+        - label: Security
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Anything else we should know? Pricing, auth requirements, whether one already exists but needs polish, related issues, etc.
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,18 +1,85 @@
-## New Server Definition
-
-**Server Name:**
-**Server ID:**
-**Transport:** stdio / http
-**Repository:**
-
-### Checklist
-
-- [ ] JSON file placed in `servers/` directory
-- [ ] File name matches server ID (e.g., `com.example.server.json`)
-- [ ] Schema validates (`npm run validate servers/your-file.json`)
-- [ ] No ID/alias conflicts (`npm run check-conflicts`)
-- [ ] Required fields: `id`, `name`, `transport`
-- [ ] Description provided
-- [ ] At least one category assigned
-- [ ] Publisher information included
-- [ ] Repository link provided
+<!--
+Thanks for contributing to the McpMux server registry!
+
+Most PRs here add or update a server definition in `servers/`. Fill in the
+sections below that apply and delete the rest. See CONTRIBUTING.md for the
+full contributor guide.
+-->
+
+## Change Type
+
+<!-- Tick one. -->
+
+- [ ] Add a new server definition
+- [ ] Update an existing server definition
+- [ ] Fix a bug in an existing definition
+- [ ] Other (describe in Summary)
+
+## Summary
+
+<!-- One or two sentences: what does this PR do and why? -->
+
+## Server Details
+
+<!-- Fill this section for Add / Update / Fix. Delete it for anything else. -->
+
+- **Server Name:**
+- **Server ID:** `community.example` or `com.publisher-name`
+- **Transport:** `stdio` / `http`
+- **Authentication:** `none` / `api_key` / `optional_api_key` / `oauth` / `basic`
+- **Categories:** <!-- from categories.json, e.g. developer-tools, productivity -->
+- **Upstream Repository:** https://github.com/...
+
+## Checklist
+
+### CI-enforced — your PR will fail without these
+
+- [ ] JSON file lives at `servers/<id>.json`
+- [ ] Filename matches the `id` field exactly
+- [ ] Required fields present: `id`, `name`, `transport`
+- [ ] `pnpm validate servers/<id>.json` passes
+- [ ] `pnpm check-conflicts` passes (no duplicate IDs or aliases)
+- [ ] `pnpm test` passes
+- [ ] Every commit is signed off — `git commit -s` (DCO)
+
+### Reviewer quality bar
+
+- [ ] `description` is one clear sentence — no marketing fluff
+- [ ] At least one category from [`categories.json`](../categories.json) is assigned
+- [ ] Every `${input:ID}` placeholder has a matching `metadata.inputs[].id`
+- [ ] Every secret / credential input is marked `"secret": true`
+- [ ] Each credential input has an `obtain` block with step-by-step instructions (numbered, `\n` between steps)
+- [ ] `auth.type` is consistent with how credentials are actually wired into the transport
+- [ ] `links.repository` resolves (when the upstream is public)
+- [ ] `capabilities` (`tools` / `resources` / `prompts` / `read_only_mode`) reflect what the server actually implements
+- [ ] `platforms` is accurate — don't claim `["all"]` without verifying Windows/macOS/Linux
+
+### Platform-managed fields — leave unset
+
+<!--
+The validator strips these; PRs that set them are rejected. See
+CONTRIBUTING.md → "Platform-Managed Fields (Do Not Set)".
+-->
+
+- [ ] I did **not** set `badges`, `stats`, `sponsored`, `featured`
+- [ ] I did **not** set `publisher.official`, `publisher.verified`, `publisher.domain_verified`
+- [ ] I did **not** add any `_platform*`-prefixed keys
+
+### Trademark & branding
+
+<!-- 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)
+
+### Tested locally (recommended for new servers)
+
+- [ ] Installed the server in McpMux and it started successfully
+- [ ] Called at least one tool / fetched at least one resource / rendered at least one prompt
+
+## Notes for Reviewers
+
+<!--
+Anything surprising, gotchas, links to upstream issues, reason for unusual
+choices, or context maintainers should know before approving.
+-->