feat: MCP SDK tier improvements

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,58 @@
+name: Bug report
+description: Report incorrect SDK behavior or interoperability
+title: "[Bug]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        For a security vulnerability, stop here and use the private process in SECURITY.md.
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened, and what did you expect instead?
+    validations:
+      required: true
+  - type: input
+    id: sdk-version
+    attributes:
+      label: SDK version or commit
+      placeholder: v0.2.0 or a full commit SHA
+    validations:
+      required: true
+  - type: input
+    id: protocol-version
+    attributes:
+      label: MCP protocol revision
+      placeholder: "2025-11-25"
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, compiler and version, build type, transport, and dependency versions.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Include the smallest source, build command, and request sequence that reproduces the issue.
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs or wire messages
+      description: Remove credentials, tokens, personal data, and other secrets.
+      render: text
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checklist
+      options:
+        - label: I searched existing issues for this problem.
+          required: true
+        - label: I removed secrets and sensitive data from the report.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/yurirocha15/mcp-cpp-sdk/security/policy
+    about: Report vulnerabilities privately; do not open a public issue.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,42 @@
+name: Feature request
+description: Propose an SDK capability or usability improvement
+title: "[Feature]: "
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What user or interoperability problem should this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+      description: Describe the public API and observable behavior you would expect.
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Client
+        - Server
+        - Protocol types
+        - Transport
+        - Authentication or security
+        - Packaging or build
+        - Documentation or examples
+    validations:
+      required: true
+  - type: input
+    id: specification
+    attributes:
+      label: Specification or SEP
+      description: Link the relevant MCP specification or SEP when applicable.
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives
+      description: What workarounds or alternative designs have you considered?

.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,25 @@
+name: Question
+description: Ask about SDK usage, behavior, or design
+title: "[Question]: "
+body:
+  - type: textarea
+    id: question
+    attributes:
+      label: Question
+      description: Include the goal you are trying to accomplish.
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: Include relevant SDK version, protocol revision, transport, and a concise code sample.
+    validations:
+      required: true
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checklist
+      options:
+        - label: I checked the README, generated documentation, and existing issues.
+          required: true

.github/labels.yml

@@ -0,0 +1,36 @@
+- name: bug
+  color: d73a4a
+  description: Confirmed or reported defect
+- name: enhancement
+  color: a2eeef
+  description: New feature or improvement
+- name: question
+  color: d876e3
+  description: Usage or design question
+- name: needs confirmation
+  color: fbca04
+  description: Needs maintainer confirmation before classification
+- name: needs repro
+  color: f9d0c4
+  description: Needs a minimal reproducible example
+- name: ready for work
+  color: 0e8a16
+  description: Triaged and ready to implement
+- name: good first issue
+  color: 7057ff
+  description: Suitable for a first contribution
+- name: help wanted
+  color: 008672
+  description: Maintainers welcome community help
+- name: P0
+  color: b60205
+  description: Critical; resolve within 14 calendar days
+- name: P1
+  color: d93f0b
+  description: High priority and severe impact
+- name: P2
+  color: fbca04
+  description: Normal project priority
+- name: P3
+  color: c5def5
+  description: Low priority or long-term work

.github/workflows/ci.yml

@@ -1,6 +1,9 @@
 name: CI
 
 on:
+  # Manual runs only. The automatic triggers below stay scoped to `main` on purpose; this
+  # lets a feature branch be checked on the full matrix without spending CI on every push.
+  workflow_dispatch:
   push:
     branches: [ main ]
   pull_request:
@@ -69,14 +72,35 @@ jobs:
         restore-keys: ${{ matrix.os }}-cxx${{ matrix.cppstd }}-${{ matrix.linkage }}-ccache-
         max-size: 500M
 
+    # MCP_REQUIRE_TWIN_LOOPBACK turns the OAuthSetterPairAtomicity skips into failures. Those tests
+    # need a port free on both 127.0.0.1 and 127.0.0.2, and skip when the second address is
+    # missing -- which would delete the whole setter-pair atomicity regression suite while the run
+    # still reported green. Linux binds 127.0.0.0/8 as a whole, so there the address is always
+    # there and its absence is a broken runner, not an unsupported host. macOS gives lo0 only
+    # 127.0.0.1 unless an alias is added, so the skip stays available there.
     - name: Build and Test
+      env:
+        MCP_REQUIRE_TWIN_LOOPBACK: ${{ runner.os == 'Linux' && '1' || '' }}
       run: >-
         python scripts/build.py --examples --test
         --cppstd ${{ matrix.cppstd }} --linkage ${{ matrix.linkage }}
 
+    # The README is the first code a new user copies, so compile it the way they
+    # would. Skipped on Windows: the check drives the compiler from
+    # compile_commands.json with GCC/Clang flag spellings.
+    - name: Compile README snippets
+      if: runner.os != 'Windows'
+      run: python scripts/check_readme_snippets.py
+
     - name: Run Examples
       run: python scripts/run_examples.py
 
+    # On the stdio transport stdout is the protocol channel. Running an example
+    # and checking its exit code does not notice prose printed there, so assert
+    # the stream separately. run_examples.py builds into build/release.
+    - name: Check stdio protocol streams
+      run: python scripts/check_stdio_streams.py build/release
+
   sanitize:
     runs-on: ubuntu-24.04
 
@@ -113,6 +137,8 @@ jobs:
         max-size: 500M
 
     - name: Build and Test with Sanitizers
+      env:
+        MCP_REQUIRE_TWIN_LOOPBACK: '1'
       run: python scripts/build.py --sanitize --test
 
   release-safety:
@@ -134,7 +160,8 @@ jobs:
         python3 scripts/check_release_workflow.py
         PYTHONPATH=scripts python3 -m unittest -v \
           scripts.test_release_dispatch_contract \
-          scripts.test_release_workflow_policy
+          scripts.test_release_workflow_policy \
+          scripts.test_check_json_matrix
 
     - name: Validate release artifacts and package templates
       run: |

.github/workflows/conformance-guards.yml

@@ -0,0 +1,32 @@
+name: Conformance guardrails
+
+on:
+  # Manual runs only. The automatic triggers below stay scoped to `main` on purpose; this
+  # lets a feature branch be checked on the full matrix without spending CI on every push.
+  workflow_dispatch:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  alpha-runner-non-gating:
+    name: Alpha runner stays non-gating
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12'
+
+      - name: Assert the alpha conformance runner cannot gate CI
+        run: python3 scripts/check_alpha_runner_guard.py

.github/workflows/conformance.yml

@@ -0,0 +1,74 @@
+name: MCP conformance regression baseline
+
+on:
+  # Manual runs only. The automatic triggers below stay scoped to `main` on purpose; this
+  # lets a feature branch be checked on the full matrix without spending CI on every push.
+  workflow_dispatch:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  conformance-2025-11-25:
+    name: Pinned client/server baseline (2025-11-25)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12'
+
+      - name: Set up Node.js
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: conformance/runner/package-lock.json
+
+      - name: Set up ccache
+        uses: hendrikmuhs/ccache-action@e42e6681d2906409c5dde4a315af6214eaa890ee # v1.2
+        with:
+          key: ubuntu-24.04-conformance
+
+      - name: Install CMake
+        uses: jwlawson/actions-setup-cmake@0d6a7d60b009d01c9e7523be22153ff8f19460d3 # v2
+        with:
+          cmake-version: '3.25'
+
+      - name: Cache Conan packages
+        uses: actions/cache@caa296126883cff596d87d8935842f9db880ef25 # v5
+        with:
+          path: ~/.conan2/p
+          key: ubuntu-24.04-conan-conformance-${{ hashFiles('conanfile.py', 'conanfile.txt') }}
+          restore-keys: ubuntu-24.04-conan-
+
+      - name: Install C++ dependencies
+        run: python3 scripts/init.py
+
+      - name: Build conformance fixtures
+        run: python3 scripts/build.py --conformance --jobs "$(nproc)"
+
+      - name: Install locked official runner
+        run: npm ci --ignore-scripts --prefix conformance/runner
+
+      - name: Run pinned regression suites
+        run: bash conformance/run.sh build/release build/conformance-results
+
+      - name: Upload conformance evidence
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: mcp-conformance-2025-11-25
+          path: build/conformance-results
+          if-no-files-found: error
+          retention-days: 30

.github/workflows/docs.yml

@@ -1,6 +1,9 @@
 name: Docs
 
 on:
+  # Manual runs only. The automatic triggers below stay scoped to `main` on purpose; this
+  # lets a feature branch be checked on the full matrix without spending CI on every push.
+  workflow_dispatch:
   push:
     branches: [main]
 

.github/workflows/release.yml

@@ -1497,16 +1497,28 @@ jobs:
         id: publish
         env:
           AUR_SSH_PRIVATE_KEY_B64: ${{ secrets.AUR_SSH_PRIVATE_KEY_B64 }}
+          AUR_SSH_KEY_PASSPHRASE: ${{ secrets.AUR_SSH_KEY_PASSPHRASE }}
           AUR_KNOWN_HOSTS: ${{ vars.AUR_KNOWN_HOSTS }}
           VERSION: ${{ needs.contract.outputs.version }}
           TAG: ${{ inputs.tag }}
         run: |
           install -d -m 700 "${HOME}/.ssh"
-          trap 'rm -f "${HOME}/.ssh/id_ed25519"' EXIT
+          umask 077
+          askpass="${RUNNER_TEMP}/aur-ssh-askpass"
+          trap 'ssh-agent -k >/dev/null 2>&1 || true; rm -f "${HOME}/.ssh/id_ed25519" "${HOME}/.ssh/known_hosts" "${askpass}"' EXIT
           printf '%s\n' "${AUR_KNOWN_HOSTS}" > "${HOME}/.ssh/known_hosts"
           grep -E '^aur\.archlinux\.org[ ,]' "${HOME}/.ssh/known_hosts" >/dev/null
           printf '%s' "${AUR_SSH_PRIVATE_KEY_B64}" | base64 --decode > "${HOME}/.ssh/id_ed25519"
           chmod 600 "${HOME}/.ssh/id_ed25519"
+          test -n "${AUR_SSH_KEY_PASSPHRASE}"
+          printf '%s\n' '#!/bin/sh' 'printf "%s\\n" "${AUR_SSH_KEY_PASSPHRASE}"' > "${askpass}"
+          chmod 700 "${askpass}"
+          export SSH_ASKPASS="${askpass}" SSH_ASKPASS_REQUIRE=force DISPLAY=release
+          eval "$(ssh-agent -s)"
+          ssh-add "${HOME}/.ssh/id_ed25519" </dev/null
+          unset AUR_SSH_KEY_PASSPHRASE SSH_ASKPASS SSH_ASKPASS_REQUIRE DISPLAY
+          rm -f "${askpass}"
+          export GIT_SSH_COMMAND="ssh -F /dev/null -o BatchMode=yes -o StrictHostKeyChecking=yes -o UserKnownHostsFile=${HOME}/.ssh/known_hosts"
           git clone --no-checkout ssh://aur@aur.archlinux.org/mcp-cpp-sdk.git aur-repository
           cd aur-repository
           git checkout HEAD -- . || true

.gitignore

@@ -65,10 +65,15 @@ build/doxygen/
 build/docs/
 docs/_build/
 
+# Conformance runner dependencies and local evidence
+conformance/runner/node_modules/
+conformance/results/
+
 # Benchmark build artifacts
 benchmark/cpp/build/
 benchmark/cpp/build-*/
 benchmark/benchmark-mcp-servers-v2/
 
 # Generated files
 compile_commands.json
+graphify-out/