Add MCP

.devcontainer/devcontainer.json

@@ -58,6 +58,13 @@
             }
         }
     },
+    "forwardPorts": [8081],
+    "portsAttributes": {
+        "8081": {
+            "label": "QDK Chemistry MCP",
+            "onAutoForward": "silent"
+        }
+    },
     "features": {
         "ghcr.io/devcontainers/features/git:1": {},
         "ghcr.io/devcontainers/features/node:2": {

.github/plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "qdk-chemistry",
+  "owner": {
+    "name": "Microsoft"
+  },
+  "metadata": {
+    "description": "QDK Chemistry agent plugins",
+    "version": "2.1.0"
+  },
+  "plugins": [
+    {
+      "name": "qdk-chemistry",
+      "description": "Run QDK Chemistry workflows with specialized agents, skills, and MCP tools.",
+      "version": "2.1.0",
+      "source": "copilot-plugins/qdk-chemistry"
+    }
+  ]
+}

.github/scripts/check_version_alignment.py

@@ -11,6 +11,9 @@
 - python/src/qdk_chemistry/utils/telemetry.py (uses importlib.metadata with fallback)
 - docs/source/conf.py (uses Path.read_text())
 - docs/source/changelog.rst (must have entry for current version)
+- copilot-plugins/qdk-chemistry/plugin.json (matches VERSION)
+- copilot-plugins/qdk-chemistry/skills/*/SKILL.md (matches VERSION)
+- .github/plugin/marketplace.json (matches plugin.json)
 
 Exit codes:
     0: All versions are aligned
@@ -22,6 +25,7 @@
 # Licensed under the MIT License. See LICENSE.txt in the project root for license information.
 # --------------------------------------------------------------------------------------------
 
+import json
 import re
 import sys
 from pathlib import Path
@@ -150,6 +154,60 @@ def check_versions() -> int:
     else:
         errors.append("docs/source/changelog.rst: file not found")
 
+    # Check 7: plugin and skill versions match VERSION
+    plugin_manifest = repo_root / "copilot-plugins/qdk-chemistry/plugin.json"
+    marketplace_manifest = repo_root / ".github/plugin/marketplace.json"
+    try:
+        plugin_version = json.loads(plugin_manifest.read_text())["version"]
+        if plugin_version != canonical_version:
+            errors.append(
+                "copilot-plugins/qdk-chemistry/plugin.json: version is "
+                f"'{plugin_version}', expected '{canonical_version}' from VERSION"
+            )
+
+        skills_directory = plugin_manifest.parent / "skills"
+        skill_files = sorted(skills_directory.glob("*/SKILL.md"))
+        if not skill_files:
+            errors.append("copilot plugin skills: no SKILL.md files found")
+        expected_skill_version = f"v{canonical_version}"
+        for skill_file in skill_files:
+            content = skill_file.read_text()
+            frontmatter = content.split("---", 2)
+            version_match = (
+                re.search(
+                    r"^version:\s*['\"]?([^'\"\s]+)['\"]?\s*$",
+                    frontmatter[1],
+                    re.MULTILINE,
+                )
+                if len(frontmatter) == 3
+                else None
+            )
+            skill_label = skill_file.relative_to(repo_root)
+            if version_match is None:
+                errors.append(f"{skill_label}: missing version in YAML frontmatter")
+            elif version_match.group(1) != expected_skill_version:
+                errors.append(
+                    f"{skill_label}: version is '{version_match.group(1)}', "
+                    f"expected '{expected_skill_version}' from VERSION"
+                )
+
+        # Check 8: plugin marketplace entries match the plugin manifest version
+        marketplace = json.loads(marketplace_manifest.read_text())
+        marketplace_versions = {
+            "metadata.version": marketplace["metadata"]["version"],
+            "plugins[0].version": marketplace["plugins"][0]["version"],
+        }
+        for field, marketplace_version in marketplace_versions.items():
+            if marketplace_version != plugin_version:
+                errors.append(
+                    f".github/plugin/marketplace.json: {field} is "
+                    f"'{marketplace_version}', expected '{plugin_version}' from plugin.json"
+                )
+    except (FileNotFoundError, IndexError, KeyError, json.JSONDecodeError) as exception:
+        errors.append(
+            f"plugin version manifests: invalid or missing data ({exception})"
+        )
+
     # Report results
     if errors:
         print("FAIL: Version check failed:", file=sys.stderr)
@@ -174,6 +232,9 @@ def check_versions() -> int:
     print("    - python/src/qdk_chemistry/utils/telemetry.py")
     print("    - docs/source/conf.py")
     print("    - docs/source/changelog.rst")
+    print("    - copilot-plugins/qdk-chemistry/plugin.json")
+    print("    - copilot-plugins/qdk-chemistry/skills/*/SKILL.md")
+    print("    - .github/plugin/marketplace.json")
     return 0
 
 

.gitignore

@@ -48,6 +48,7 @@ pip-delete-this-directory.txt
 
 # Unit test / coverage reports
 htmlcov/
+
 .tox/
 .nox/
 .coverage

.pipelines/pip-scripts/test-pip-wheels-windows.ps1

@@ -11,6 +11,7 @@ param(
     [string]$SrcDir        = (Resolve-Path "$PSScriptRoot\..\.." -ErrorAction Stop),
     [string]$PythonVersion = '3.11',
     [string]$RunSlowTests  = 'true',
+    [string]$Triplet       = $env:VCPKG_TRIPLET,
     [ValidateSet('conda', 'venv')]
     [string]$PythonEnv     = 'conda'
 )
@@ -48,6 +49,10 @@ Write-Host "Installing: $wheel"
 if ($LASTEXITCODE -ne 0) { throw "pip upgrade failed ($LASTEXITCODE)" }
 & $runExe @runArgs -m pip install "$wheel[test]"
 if ($LASTEXITCODE -ne 0) { throw "pip install wheel[test] failed ($LASTEXITCODE)" }
+if ($Triplet -ne 'arm64-windows-static-md') {
+    & $runExe @runArgs -c "import mcp; from qdk_chemistry.ui._mcp import MCP_AVAILABLE; assert MCP_AVAILABLE"
+    if ($LASTEXITCODE -ne 0) { throw "MCP installation smoke test failed ($LASTEXITCODE)" }
+}
 
 # ─── 3. Component Governance PipReport (non-fatal) ───────────────────────────
 Write-Host "=== Generate Component Governance PipReport ==="

.pipelines/templates/test-pip-wheels-windows.yml

@@ -34,6 +34,7 @@ steps:
       -SrcDir "$(System.DefaultWorkingDirectory)" `
       -PythonVersion '${{ parameters.pythonVersion }}' `
       -PythonEnv $pythonEnv `
+      -Triplet '$(VCPKG_TRIPLET)' `
       -RunSlowTests '${{ parameters.runSlowTests }}'
   displayName: Test wheel (Windows, Python ${{ parameters.pythonVersion }})
   condition: ${{ parameters.condition }}

.pre-commit-config.yaml

@@ -89,6 +89,7 @@ repos:
   hooks:
   - id: markdownlint
     args: [--fix, --disable=line-length, --disable=MD024, --disable=MD029, --disable=MD033]
+    exclude: (agent_configs/|^copilot-plugins/)
     files: &all_md >
       (?x)^(
         .*\.md$|
@@ -125,9 +126,14 @@ repos:
     require_serial: true
     files: >
       (?x)^(
+        VERSION|
         python/CMakeLists\.txt|
         cpp/CMakeLists\.txt|
-        docs/source/conf\.py
+        docs/source/conf\.py|
+        \.github/scripts/check_version_alignment\.py|
+        copilot-plugins/qdk-chemistry/plugin\.json|
+        copilot-plugins/qdk-chemistry/skills/[^/]+/SKILL\.md|
+        \.github/plugin/marketplace\.json
       )$
 
   - id: check-pyi-stubs

INSTALL.md

@@ -88,6 +88,7 @@ python3 -m pip install qdk-chemistry
 > **NOTE:** On Python 3.14, `qiskit-aer` is omitted from the `qiskit-extras` and `all` extras on Linux ARM64 (aarch64), because Qiskit does not yet publish a Python 3.14 wheel for that platform. See the [Optional Extras](#optional-extras) table below for details.
 >
 > **NOTE:** On Windows, PySCF is skipped from the `plugins` extra because it publishes no Windows wheels; on Windows arm64 the Qiskit stack, PennyLane, RDKit and the Discovery backend are skipped as well. See [Notes for Windows users](#notes-for-windows-users).
+> The MCP extra is also omitted from `[all]` and `[test]` on Windows arm64.
 
 ### Step 3: Verify the installation
 
@@ -118,15 +119,16 @@ If you chose the minimal `pip install qdk-chemistry` above, you can add specific
 |-------|-------------|-------------------|
 | `coverage` | Coverage reporting tools | coverage, pytest, pytest-cov, gcovr |
 | `jupyter` | Jupyter notebook support | ipykernel, pandas |
+| `mcp` | MCP server, transports, workspace binding, and MCP Apps integration | mcp |
 | `plugins` | Third-party quantum chemistry backends | PySCF (no Windows wheels) |
 | `qiskit-extras` | Qiskit ecosystem packages | qiskit, qiskit-aer, qiskit-nature |
 | `openfermion-extras` | OpenFermion ecosystem packages | openfermion |
 | `networkx-extras` | NetworkX ecosystem packages | networkx |
 | `docs` | [Sphinx documentation build tools](docs/README.md) | sphinx, sphinx-rtd-theme, myst-parser, breathe, sphinx-autodoc-typehints, sphinx-inline-tabs, sphinxcontrib-napoleon, sphinxcontrib-bibtex, sphinx_copybutton |
 | `qre` | Quantum Resource Estimator support | qdk[qre,jupyter]>=1.30.0 |
 | `dev` | Development and testing tools | pytest, ruff, mypy, and related tooling |
-| `test` | Testing tools and optional runtime dependencies; does not include `docs` | qdk-chemistry[coverage,jupyter,networkx-extras,openfermion-extras,plugins,qiskit-extras,qre], nbclient, nbformat, pennylane, rdkit, requests>=2.33.0 |
-| `all` | Union of all defined extras | coverage, dev, docs, jupyter, networkx-extras, openfermion-extras, plugins, qiskit-extras, qre, test |
+| `test` | Testing tools and optional runtime dependencies; does not include `docs` | qdk-chemistry[coverage,jupyter,mcp,networkx-extras,openfermion-extras,plugins,qiskit-extras,qre], nbclient, nbformat, pennylane, rdkit, requests>=2.33.0 |
+| `all` | Union of all defined extras | coverage, dev, docs, jupyter, mcp, networkx-extras, openfermion-extras, plugins, qiskit-extras, qre, test |
 
 To build the documentation, install the `docs` extra (for example,
 `python3 -m pip install 'qdk-chemistry[docs]'`), install the Doxygen system
@@ -168,7 +170,7 @@ to native Windows installs; none of them apply under
 | Topic | Detail |
 |-------|--------|
 | PySCF plugin | PySCF publishes no Windows wheels, so the `plugins` extra installs no PySCF and the PySCF plugin is unavailable. The native implementations are unaffected. |
-| arm64 extras | Qiskit (and Qiskit Aer, Nature, IBM Runtime), PennyLane and RDKit are skipped on arm64: they require `rustworkx`, which publishes no win-arm64 wheels. The Discovery backend (`azure-ai-discovery`, `azure-identity`, `azure-storage-blob`) is skipped as well: it requires `cryptography`, which publishes no win-arm64 wheel and needs a Rust toolchain plus OpenSSL to build from source. The features that depend on them are unavailable; everything else is unaffected. |
+| arm64 dependencies and extras | MCP is omitted from the `all` and `test` extras because its `cryptography` dependency publishes no win-arm64 wheel. A base, `all`, or `test` install therefore needs neither Rust nor a source build of `cryptography`; installing the `mcp` extra explicitly may require an ARM64 Rust toolchain, MSVC C/C++ build tools, and ARM64 OpenSSL development libraries. Qiskit (and Qiskit Aer, Nature, IBM Runtime), PennyLane and RDKit are skipped because they require `rustworkx`, which also publishes no win-arm64 wheel. The Discovery backend (`azure-ai-discovery`, `azure-identity`, `azure-storage-blob`) is skipped as well. The features that depend on those skipped extras are unavailable. |
 | OpenMP | Shared-memory threading via OpenMP is disabled on Windows. |
 
 ---

README.md

@@ -61,11 +61,73 @@ python -m pip install "qdk-chemistry[all]"
 ```
 
 The `[all]` extra pulls in all optional dependencies so that examples and tests work without chasing missing packages. For other installation methods (Dev Container, building from source) and platform-specific notes, see [INSTALL.md](./INSTALL.md).
+On Windows arm64, dependencies without native wheels, including MCP, are omitted from `[all]`.
 
 Prebuilt wheels are published for Linux (x86_64, arm64), macOS (Apple Silicon), and Windows (x86_64, arm64). On Windows, [WSL](https://learn.microsoft.com/windows/wsl/install) is supported as well. See [Notes for Windows users](./INSTALL.md#notes-for-windows-users) for Windows-specific caveats.
 
 For a complete, end-to-end walkthrough from installation through a full quantum chemistry pipeline, see the [Quickstart guide](https://microsoft.github.io/qdk-chemistry/user/quickstart.html) and the [examples/](./examples/) directory.
 
+## Copilot Plugin
+
+QDK Chemistry publishes a Copilot plugin containing skills and an MCP server
+configuration. Register the repository marketplace, then run the plugin
+installer from the virtual environment containing QDK Chemistry:
+
+```bash
+python -m pip install 'qdk-chemistry[mcp]'
+copilot plugin marketplace add https://github.com/microsoft/qdk-chemistry.git
+qc plugin install qdk-chemistry@qdk-chemistry
+```
+
+Installing the `mcp` extra automatically activates the server endpoint, tool
+registration, workspace middleware, and available MCP Apps visualizations.
+The `qc` CLI remains available without this extra.
+
+With no target directory, Copilot installs the plugin for the current user and
+QDK Chemistry pins its MCP command to that virtual environment. A local plugin
+directory is also accepted; QDK Chemistry registers its ancestor marketplace in
+the same Copilot scope before installation. Copilot repository subdirectory
+specs are accepted directly:
+
+```bash
+qc plugin install ./copilot-plugins/qdk-chemistry
+qc plugin install OWNER/REPO:copilot-plugins/qdk-chemistry
+```
+
+To configure one workspace instead, pass its root. QDK Chemistry copies the
+fetched skills into `.github`, merges its MCP server into
+`.vscode/mcp.json` and `.github/mcp.json`, and keeps fetch/update state beneath
+the ignored `.qdk_chem` directory:
+
+```bash
+qc plugin install ./copilot-plugins/qdk-chemistry \
+    --target-dir /path/to/workspace
+```
+
+Update through the same CLI so the virtual-environment binding is restored
+after Copilot refreshes the plugin files. Pass the same `--target-dir` for a
+workspace installation:
+
+```bash
+qc plugin update qdk-chemistry
+qc plugin update --all
+qc plugin rebind qdk-chemistry
+```
+
+VS Code discovers user plugins installed by Copilot CLI and workspace assets
+written by `--target-dir`. The plugin supplies:
+
+- QDK Chemistry overview, MCP, coding, remote-execution, and visualization skills; and
+- the `qdk_chemistry` MCP server configuration.
+
+Plugin MCP processes start in the installed plugin directory. Call
+`bind_workspace` before any other QDK Chemistry tool. It uses a single
+client-provided file root when available; otherwise pass the active workspace as
+an absolute `workspace_root`. Plugin-launched servers reject other tool calls
+until binding succeeds and cannot be rebound to another workspace.
+
+**Skills** provide tested domain knowledge: tool references, workflow recipes, parameter guidance, and common pitfalls.
+
 ## Telemetry
 
 By default, this library collects anonymous usage and performance data to help improve the user experience and product quality. The telemetry implementation can be found in [telemetry.py](./python/src/qdk_chemistry/utils/telemetry.py) and all telemetry events are defined in [telemetry_events.py](./python/src/qdk_chemistry/utils/telemetry_events.py).

copilot-plugins/qdk-chemistry/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "qdk_chemistry": {
+      "type": "stdio",
+      "command": "qcmcp",
+      "timeout": 1814400000,
+      "env": {
+        "QDK_REQUIRE_WORKSPACE_BINDING": "1"
+      }
+    }
+  }
+}

copilot-plugins/qdk-chemistry/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "qdk-chemistry",
+  "description": "Use QDK Chemistry through skills and MCP tools.",
+  "version": "2.1.0",
+  "author": {
+    "name": "Microsoft"
+  },
+  "skills": "skills/",
+  "mcpServers": ".mcp.json"
+}

copilot-plugins/qdk-chemistry/skills/qdk-chemistry-coding/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: qdk-chemistry-coding
+version: 'v2.1.0'
+description: 'Describes the Python API for discovering, configuring, and executing QDK Chemistry algorithms.'
+---
+
+# QDK Chemistry Python API
+
+Algorithms are obtained from the registry:
+
+- `available(algorithm_type)` returns registered implementations.
+- `show_default(algorithm_type)` returns the registered default.
+- `create(algorithm_type, algorithm_name, **settings)` creates an algorithm.
+- `algorithm.settings()` returns its settings object.
+- `algorithm.run(...)` executes it.
+- `algorithm.hash(...)` computes the content hash for a call.
+- `algorithm.run(..., remote=name_or_backend)` executes it through a registered
+	remote backend and waits for the result.
+
+Algorithm `run` signatures and data-class APIs define accepted inputs and
+returned objects. Coordinates supplied to `Structure` are in Bohr. The
+registry defines installed algorithm types, implementation names, settings,
+and defaults.
+
+## Settings
+
+`settings()` returns typed setting entries. `get(name)` reads a value and
+`set(name, value)` changes it before execution. Algorithm references encode a
+nested algorithm selection and its nested settings. Validation errors identify
+unknown setting names or incompatible values.
+
+## Execution and Results
+
+Each algorithm class defines its own `run(...)` signature. Inputs include data
+objects and scalar configuration such as charge or multiplicity where required.
+Returns may be a data object, a scalar, or a tuple. The API documentation for
+the selected class defines the exact return shape.
+
+Data objects support JSON or HDF5 serialization according to their class API.
+Serialized files can be loaded and passed to later calls that accept the same
+data type.
+
+## Content Hashes
+
+Algorithms and data objects expose deterministic content hashes. An algorithm
+call hash includes the implementation, settings, and inputs. Cache backends use
+that identity to associate a call with serialized outputs.
+
+## Remote Execution
+
+`algorithm.run(..., remote=name_or_backend)` routes a call through a registered
+backend and returns the same result shape as local execution. The module-level
+`qdk_chemistry.remote.run(algorithm, ..., remote=name_or_backend)` function
+provides the same blocking behavior for any compatible algorithm object.
+
+For asynchronous execution,
+`qdk_chemistry.remote.submit(algorithm, ..., remote=name_or_backend)` returns a
+`Job`. A job can be checked, waited on, fetched, canceled, saved, and loaded.
+Pass `job_dir` to `submit` to save its record automatically; otherwise the job
+is returned in memory.
+
+Use `available_backends()` to inspect registered SDK backends and
+`create_remote(name, **configuration)` to create a connected backend instance.
+The package ships only the `local` subprocess backend. Installed plugins can
+register additional backends.