Rebuild MCP Apps UI, expand docs, prepare 1.0.0 for NuGet

- MCP Apps UI: ext-apps 2, React 19, Vite 8, Tailwind 4; one folder per view,
  shared host connection, zod-validated tool outputs, failed/cancelled results
  shown in the view, dev sandbox left out of production bundles, per-entry or
  full builds; projects-dashboard sample with drill-down via list_projects
  (now returns structured content)
- CI builds the UI and fails on stale ui_dist bundles
- Docs: development guide index, testing guide, ADR-0004, structured content
- Package: exclude .env and other local-only files from the nupkg, guard in
  CI and publish; NuGet description and tags
- README rewritten for NuGet with screenshots; CHANGELOG as 1.0.0

Author: mostafa6765

.github/workflows/publish.yml

@@ -20,6 +20,11 @@ jobs:
         run: |
           VERSION="${GITHUB_REF_NAME#v}"
           dotnet pack TemplatePack.csproj -c Release -o artifacts -p:PackageVersion=$VERSION
+      - name: Package contains no local-only files
+        run: |
+          if unzip -l artifacts/*.nupkg | awk '{print $4}' | grep -E '(^|/)\.env(\..+)?$' | grep -v '\.env\.example$'; then
+            echo "::error::The package contains a .env file"; exit 1
+          fi
       - name: Push to nuget.org
         run: >
           dotnet nuget push "artifacts/*.nupkg"

.github/workflows/template-ci.yml

@@ -36,3 +36,31 @@ jobs:
 
       - name: Pack the template
         run: dotnet pack TemplatePack.csproj -c Release -o artifacts
+
+      - name: Package contains no local-only files
+        run: |
+          if unzip -l artifacts/*.nupkg | awk '{print $4}' | grep -E '(^|/)\.env(\..+)?$' | grep -v '\.env\.example$'; then
+            echo "::error::The package contains a .env file"; exit 1
+          fi
+
+  # The template's MCP App views: typecheck, build, and check the committed bundles are current.
+  ui:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: templates/DotnetMcpTemplate/ui
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: corepack enable
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+      - name: Committed bundles match the source
+        run: |
+          if ! git diff --quiet -- ../src/DotnetMcpTemplate/ui_dist; then
+            git diff --stat -- ../src/DotnetMcpTemplate/ui_dist
+            echo "::error::ui_dist/ is out of date. Run 'pnpm run build' in templates/DotnetMcpTemplate/ui and commit the result."
+            exit 1
+          fi

CHANGELOG.md

@@ -1,42 +1,33 @@
 # Changelog
 
-## [Unreleased]
+## [1.0.0] - 2026-09-27
 
-### Changed
-
-- Folder layout: tools, resources and prompts live in `Capabilities/`; external API clients in `Integrations/`;
-  plumbing in `Core/` (`ApiClients` base, `Auth`, `Mcp` with `Filters/` and `Apps/`, `Validation`, `Common`,
-  `ServerInfo`). Namespaces follow folders and tests mirror the source tree. `AddApiClients` is now `AddIntegrations`.
-- `global.json` pins the .NET SDK (CI and Docker use it).
-- Watch mode: `dotnet watch` + `pnpm run watch` documented in getting-started; in dev, MCP App bundles are read
-  from the project's `ui_dist/`, so rebuilt bundles are served without a restart.
-- Startup logs the public URL (`Server running at ...`) next to Kestrel's `http://[::]:port` bind address.
-- Consent page redesigned after the FastMCP OAuth proxy screen: server and client names, the redirect URI in a
-  "Credentials will be sent to" box, collapsible advanced details (client id, scopes), Allow Access / Deny, a
-  "Why am I seeing this?" tooltip and dark mode. The error page uses the same style.
-- Docs: index at `docs/README.md`, a scopes section and OIDC callback / discovery troubleshooting in the auth guide,
-  and updated paths in every guide.
-- Scopes are defined in code (`Core/Auth/AppScopes.cs`) instead of `AUTH_SCOPES_SUPPORTED`; the dev user always has
-  every scope and the `admin` role (`AUTH_DEV_USER_ROLES` removed).
-
-### Fixed
-
-- A client that requests no scope now gets no extra permissions instead of every scope.
-- The server listens on IPv4 and IPv6, so `localhost` works when it resolves to `::1`.
-- `Microsoft.Extensions.Http.Resilience` pinned to 10.9.0 (10.8.3 does not exist, NU1603).
-- CS0114 warning on `ApiClientException.Source`, and a unit test that did not compile.
-
-## [1.0.0] - 2026-09-26
+First release.
 
 ### Added
 
-- MCP server on ASP.NET Core with ModelContextProtocol.AspNetCore 2.0 (stateless Streamable HTTP).
-- Tools, resources (templated, direct, MCP App `ui://`) and prompts, grouped by component, on a service layer.
-- Argument validation for tools and prompts (data annotations, nested objects, `IValidatableObject`).
-- Auth: OIDC proxy for any identity provider (DCR, consent, PKCE, ID token + userinfo merge, rotating refresh
-  tokens, encrypted IdP tokens), `jwt` resource-server provider, extensible `IAuthProvider`, dev mode.
-- Typed API clients (`ApiClient` base) with env-configured auth, retries, circuit breaker, timeouts, correlation ids.
-- MCP Apps with the SDK extension, `ui/` React + Vite workspace and a placeholder bundle.
-- `.env` settings (DotNetEnv + validated typed settings), `APP_PORT`, minimal JSON server info at `/`.
-- Unit, integration (real MCP client, full OAuth flow against a fake IdP) and architecture tests.
-- Dockerfile (optional UI build stage), Compose, CI, ADRs and guides.
+- **MCP server** on ASP.NET Core (.NET 10) with ModelContextProtocol.AspNetCore 2.0: stateless Streamable HTTP;
+  tools, resources (templated, direct, MCP App `ui://`) and prompts discovered from attributes; structured content.
+- **Layout:** `Capabilities/` (tools, resources, prompts), `Services/`, `Models/`, `Integrations/` (external API
+  clients), `Core/` (auth, MCP setup and filters, validation, settings, errors, server info). Namespaces follow
+  folders; tests mirror the source tree; architecture tests enforce the call direction and auth on every item.
+- **Validation** of every tool and prompt call (data annotations, nested objects, `IValidatableObject`), returned as
+  errors the model can fix.
+- **Auth:** OIDC proxy for any OIDC identity provider (dynamic client registration, PKCE, ID token + userinfo merge,
+  rotating refresh tokens, encrypted IdP tokens, memory or Redis store), consent page in the style of the FastMCP
+  OAuth proxy, `jwt` resource-server provider, extensible `IAuthProvider`, dev mode. Scopes are defined in code
+  (`Core/Auth/AppScopes.cs`); clients get only the scopes they request.
+- **MCP Apps UI** (`ui/`): ext-apps 2, React 19, Vite 8, Tailwind 4. One folder per view, shared host connection
+  (`useToolOutput`, `useCallTool`, `useMcpApp`), host theme tokens, zod-validated tool outputs, failed / cancelled
+  results shown in the view, dev sandbox with sample data (left out of production bundles), per-entry or full
+  builds. Sample `projects-dashboard` with drill-down through `list_projects`.
+- **Typed API clients** (`ApiClient` base) with env-configured auth (`bearer`, `api_key`, `basic`,
+  `client_credentials`, user token), retries, circuit breaker, timeouts, correlation ids.
+- **Settings:** `.env` (DotNetEnv) plus typed settings validated at startup; `APP_PORT`, `APP_URL`; dual-stack
+  listening (`localhost`, `127.0.0.1`, `[::1]`); startup logs the public URL; minimal JSON server info at `/`.
+- **Dev loop:** `dotnet watch` and `pnpm run watch`; rebuilt MCP App bundles are served without a restart.
+- **Tests:** unit, integration (a real MCP client, including the full OAuth flow against a fake IdP) and
+  architecture tests.
+- **Ship:** multi-stage Dockerfile (optional UI build), Compose, GitHub Actions (build, test, UI bundle check,
+  Docker), `global.json`, central package management.
+- **Docs:** 10 guides indexed by task (`docs/development/README.md`) and 4 ADRs.

README.md

@@ -1,76 +1,143 @@
 # .NET MCP Server Template
 
-A `dotnet new` template for **Model Context Protocol servers** on ASP.NET Core (.NET 10) with the official
-MCP C# SDK 2.0.
+[![NuGet](https://img.shields.io/nuget/v/Code4mk.McpServer.Template?logo=nuget&label=NuGet)](https://www.nuget.org/packages/Code4mk.McpServer.Template)
+[![Downloads](https://img.shields.io/nuget/dt/Code4mk.McpServer.Template?label=downloads)](https://www.nuget.org/packages/Code4mk.McpServer.Template)
+[![template-ci](https://github.com/code4mk/dotnet-mcp-server-template/actions/workflows/template-ci.yml/badge.svg)](https://github.com/code4mk/dotnet-mcp-server-template/actions/workflows/template-ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/code4mk/dotnet-mcp-server-template/blob/main/LICENSE)
+
+**A production-ready [Model Context Protocol](https://modelcontextprotocol.io) server for ASP.NET Core in one
+command.** Sign-in with any identity provider, interactive UIs inside the chat, typed API clients, tests, Docker and
+docs: the parts that take weeks are already done, so you write tools.
 
 ```bash
 dotnet new install Code4mk.McpServer.Template
-dotnet new code4mk-mcp -n NexusRE.Mcp -o nexusre-mcp
+dotnet new code4mk-mcp -n Acme.Mcp -o acme-mcp
 ```
 
-## What you get
+Built on the official [MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk) 2.0 and .NET 10.
 
-| Area | Included |
+## Why this template
+
+**Remote MCP servers need real OAuth, and that's the hard part.** MCP clients such as Claude expect OAuth 2.1 with
+dynamic client registration, PKCE, and protected resource metadata. Most identity providers (Entra ID, Google,
+Okta, ...) don't offer dynamic registration. This template ships an **OIDC proxy** that makes any OIDC provider work
+with three settings, including the consent screen, encrypted token storage, rotating refresh tokens and Redis for
+multiple instances.
+
+**Tools can show real UI, not just text.** [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) are wired
+end to end: React + Tailwind views that follow the host's theme, call your tools themselves (paging, drill-down),
+validate every response, and preview with sample data without a server.
+
+**The structure stays clean as it grows.** Tools → services → integrations, one direction, enforced by
+architecture tests: the build fails if a tool skips auth, calls an API directly, or leaks external models.
+
+**Errors the model can fix.** Every tool and prompt argument is validated before your code runs; the model gets a
+list like `request.durationDays: High-priority projects must be 90 days or less.` and retries correctly.
+
+| | |
 | --- | --- |
-| MCP | Tools, resources, prompts (all three), stateless Streamable HTTP, MCP Apps (`ui://` bundles) |
-| Structure | `Capabilities/` (tools, resources, prompts), `Services/`, `Models/`, `Integrations/`; plumbing in `Core/` |
-| Validation | Every tool/prompt call validated from data annotations; clear errors the model can fix |
-| Auth | OIDC proxy for **any** OIDC identity provider (discovery URL + client id + optional secret + scopes), ID token + userinfo merged into one identity; `jwt` provider; custom providers via `IAuthProvider`; per-item `[Authorize]` / `[AllowAnonymous]`, scope and role policies |
-| API clients | `ApiClient` base + one line per data source; auth, retries, circuit breaker, timeouts from `{PREFIX}_*` env vars |
-| Settings | `.env` + validated typed settings (same pattern as dotnet-api-template), `APP_PORT`, `APP_URL` |
-| Server info | `GET /` → `{ name, version, status, mcp }` |
-| Tests | Unit, integration (real MCP client; full OAuth flow against a fake IdP), architecture rules |
-| DevOps | Dockerfile (+ optional UI build), Compose, GitHub Actions, ADRs and guides |
-
-## 1. Install
+| ![MCP App: projects dashboard with drill-down](https://raw.githubusercontent.com/code4mk/dotnet-mcp-server-template/main/assets/mcp-app-dashboard.png) | ![Consent page shown before a new MCP client connects](https://raw.githubusercontent.com/code4mk/dotnet-mcp-server-template/main/assets/consent-page.png) |
+| An MCP App: the tool's result as a dashboard; selecting an owner calls another tool from the view | Consent before a new MCP client connects, then sign-in at your identity provider |
+
+## Quick start
 
 ```bash
-dotnet new install Code4mk.McpServer.Template        # from nuget.org
-# or from source:
-git clone https://github.com/code4mk/dotnet-mcp-server-template && dotnet new install ./dotnet-mcp-server-template/templates/DotnetMcpTemplate
+dotnet new install Code4mk.McpServer.Template
+dotnet new code4mk-mcp -n Acme.Mcp -o acme-mcp
+cd acme-mcp
+cp .env.example .env                   # set MCP_AUTH_MODE=none for a first run without an identity provider
+dotnet watch --project src/Acme.Mcp    # → Server running at http://localhost:5080
+npx @modelcontextprotocol/inspector    # Streamable HTTP → http://localhost:5080/mcp
 ```
 
-## 2. Create a project
+`-n` is the .NET name (PascalCase), `-o` the folder. Namespaces, the solution, Docker names and GUIDs follow it.
 
-Run it outside this repository:
+**Connect a real identity provider:** register one web app with redirect URI `http://localhost:5080/oauth/callback`,
+then set `OIDC_DISCOVERY_URL`, `OIDC_CLIENT_ID` and `OIDC_CLIENT_SECRET` in `.env` and `MCP_AUTH_MODE=required`.
+Add the server in Claude (Settings → Connectors → Add custom connector) and it opens your login page.
 
-```bash
-dotnet new code4mk-mcp -n NexusRE.Mcp -o nexusre-mcp
-```
+## What you get
 
-`-n` is the .NET name (PascalCase, no dashes), `-o` the folder / repo name. Every `DotnetMcpTemplate` becomes
-`NexusRE.Mcp`; Docker names become `nexusre-mcp`; GUIDs are regenerated.
+| Area | Included |
+| --- | --- |
+| **MCP** | Tools, resources and prompts discovered from attributes; stateless Streamable HTTP (scales horizontally); annotations; structured content with output schemas |
+| **Auth** | OIDC proxy for any OIDC provider (Entra ID, Google, Auth0, Okta, Keycloak, Zitadel, ...): DCR, PKCE, consent, ID token + userinfo merged into one `AppUser`. Or the `jwt` provider, or your own `IAuthProvider`. `[Authorize]` per item, scope and role policies |
+| **MCP Apps** | `ui/` workspace (React 19, Vite, Tailwind 4, ext-apps 2): one bundle per view, host theme, tool calls from the view, zod-validated outputs, sandbox preview, per-entry builds |
+| **Validation** | Data annotations and `IValidatableObject` on every tool and prompt call, nested objects included |
+| **Integrations** | Typed API clients from one line of registration; retries, circuit breaker, timeouts; `bearer`, `api_key`, `basic`, `client_credentials`, or the signed-in user's token |
+| **Settings** | `.env` plus typed settings classes validated at startup, every problem listed by variable name |
+| **Dev loop** | `dotnet watch` with hot reload, `pnpm run watch` for views, dual-stack `localhost`, startup URL in the log |
+| **Tests** | Unit, integration (a real MCP client against the in-memory server, including the full OAuth flow against a fake IdP) and architecture rules: 64 tests out of the box |
+| **Ship** | Multi-stage Dockerfile, Compose, GitHub Actions (build, test, UI bundle check, Docker), pinned SDK, central package versions |
+| **Docs** | 10 guides organized by task, 4 architecture decision records |
+
+## Project layout
 
-## 3. Run
+```text
+acme-mcp/
+├── src/Acme.Mcp/
+│   ├── Capabilities/       Tools/, Resources/, Prompts/: what the server exposes (thin)
+│   ├── Services/           Business logic
+│   ├── Models/             Request / response DTOs
+│   ├── Integrations/       One folder per external API
+│   ├── Core/               Auth, MCP setup and filters, validation, settings, errors: plumbing you rarely touch
+│   └── ui_dist/            Built MCP App bundles
+├── ui/                     MCP App views (React + Vite + Tailwind)
+├── tests/                  Unit, Integration, Architecture (mirror src/)
+├── docs/                   Guides and ADRs
+└── docker/                 Dockerfile, Compose
+```
 
-```bash
-cd nexusre-mcp
-cp .env.example .env               # set MCP_AUTH_MODE=none for a first run without an IdP
-dotnet test
-dotnet run --project src/NexusRE.Mcp
-npx @modelcontextprotocol/inspector   # Streamable HTTP → http://localhost:5080/mcp
+Adding a tool is one class; there is no registration line:
+
+```csharp
+[McpServerToolType]
+[Authorize]
+public sealed class InvoiceTools(IInvoiceService invoices)
+{
+    [McpServerTool(Name = "get_invoice", ReadOnly = true, UseStructuredContent = true)]
+    [Description("Gets an invoice by number.")]
+    public Task<InvoiceDto> GetInvoice(
+        [Required, RegularExpression("^INV-[0-9]{6}$")] string number,
+        AppUser user,
+        CancellationToken cancellationToken) =>
+        invoices.GetAsync(number, user, cancellationToken);
+}
 ```
 
-Then connect your identity provider: register one app with redirect URI `${APP_URL}/oauth/callback` and set
-`OIDC_DISCOVERY_URL`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_SCOPES`. Full guides are in each project's `docs/`.
+## Works with
 
-Hidden files (`.env.example`, `.gitignore`, `.github/`, `.template.config/`) start with a dot: show hidden files
-in Finder (`Cmd+Shift+.`) or Explorer.
+- **Clients:** Claude (claude.ai and Desktop), VS Code, Cursor, MCP Inspector, and any client that speaks Streamable HTTP with OAuth.
+- **Identity providers:** anything with an OpenID Connect discovery URL.
+- **Hosting:** anywhere a container runs; set `APP_URL` behind a reverse proxy.
 
-## Repository layout
+## Documentation
 
-```text
-dotnet-mcp-server-template/
-├── README.md, CHANGELOG.md, LICENSE
-├── TemplatePack.csproj              packs the template (dotnet pack)
-├── .github/workflows/               template-ci (create + build + test a project), publish (nuget.org on tags)
-└── templates/DotnetMcpTemplate/     the template
+Each generated project includes its docs. Browse them on GitHub:
+
+- [Development guides](https://github.com/code4mk/dotnet-mcp-server-template/blob/main/templates/DotnetMcpTemplate/docs/development/README.md): getting started, configuration, tools, validation, MCP Apps, API clients, auth, testing, connecting clients
+- [MCP Apps UI workspace](https://github.com/code4mk/dotnet-mcp-server-template/blob/main/templates/DotnetMcpTemplate/ui/README.md)
+- [Architecture decisions](https://github.com/code4mk/dotnet-mcp-server-template/blob/main/templates/DotnetMcpTemplate/docs/README.md)
+- [Changelog](https://github.com/code4mk/dotnet-mcp-server-template/blob/main/CHANGELOG.md)
+
+**Requirements:** .NET 10 SDK. Optional: Docker; Node 22+ and pnpm for MCP App views.
+
+## Contributing
+
+Issues and pull requests are welcome. To work on the template itself:
+
+```bash
+git clone https://github.com/code4mk/dotnet-mcp-server-template
+dotnet new install ./dotnet-mcp-server-template/templates/DotnetMcpTemplate --force
+dotnet new code4mk-mcp -n Sample.Mcp -o ../sample-mcp     # always create projects outside the repo
 ```
 
-## Maintaining
+- `DotnetMcpTemplate` (and `dotnetmcptemplate-slug`) are placeholders; keep them. Package versions live in
+  `templates/DotnetMcpTemplate/Directory.Packages.props`.
+- CI creates a project from the template, builds and tests it, checks the UI bundles, and packs the template.
+- Release: update `CHANGELOG.md`, then `git tag v1.1.0 && git push origin v1.1.0`; the publish workflow pushes to
+  nuget.org (secret `NUGET_API_KEY`).
+
+## License
 
-- Keep `DotnetMcpTemplate` (and `dotnetmcptemplate-slug`) as placeholders. Never create projects inside this repo.
-- Versions live in `templates/DotnetMcpTemplate/Directory.Packages.props`.
-- Test: `dotnet new install ./templates/DotnetMcpTemplate --force`, create a project elsewhere, `dotnet build && dotnet test`.
-- Publish: update CHANGELOG, `git tag v1.1.0 && git push origin v1.1.0` (needs secret `NUGET_API_KEY`), or manually:
-  `dotnet pack TemplatePack.csproj -c Release -o artifacts -p:PackageVersion=1.1.0` then `dotnet nuget push`.
+[MIT](https://github.com/code4mk/dotnet-mcp-server-template/blob/main/LICENSE) © Code4mk