Initial commit: code4mk MCP server template

ASP.NET Core MCP server template (official C# SDK 2.0): tools, resources,
prompts, MCP Apps, OIDC proxy auth for any IdP, typed API clients,
validation, Docker, tests and docs.

- Folder layout: Capabilities/ (tools, resources, prompts), Services/,
  Models/, Integrations/ (external API clients), Core/ (plumbing)
- Scopes defined in code; clients get only the scopes they request
- Dual-stack listening (localhost, 127.0.0.1, [::1]); startup logs the URL
- Consent page redesigned after the FastMCP OAuth proxy screen
- Watch mode for local development; global.json pins the SDK

Author: mostafa6765

.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: publish
+
+# Publishes to nuget.org on tags like v1.2.0. Needs the repository secret NUGET_API_KEY (glob Code4mk.*).
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 10.0.x
+      - name: Pack
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          dotnet pack TemplatePack.csproj -c Release -o artifacts -p:PackageVersion=$VERSION
+      - name: Push to nuget.org
+        run: >
+          dotnet nuget push "artifacts/*.nupkg"
+          --source "https://api.nuget.org/v3/index.json"
+          --api-key "${{ secrets.NUGET_API_KEY }}"
+          --skip-duplicate

.github/workflows/template-ci.yml

@@ -0,0 +1,38 @@
+name: template-ci
+
+# Proves the template works: install it, create a project, build and test that project.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 10.0.x
+
+      - name: Install template from source
+        run: dotnet new install ./templates/DotnetMcpTemplate
+
+      - name: Create a sample project
+        run: dotnet new code4mk-mcp -n Sample.Mcp -o "$RUNNER_TEMP/sample-mcp"
+
+      - name: Build and test the sample project
+        working-directory: ${{ runner.temp }}/sample-mcp
+        run: |
+          dotnet build -c Release
+          dotnet test -c Release --no-build
+
+      - name: Check that no placeholder names are left
+        working-directory: ${{ runner.temp }}/sample-mcp
+        run: |
+          if grep -rIi --exclude-dir=bin --exclude-dir=obj "dotnetmcptemplate" .; then
+            echo "Found leftover placeholder"; exit 1
+          fi
+
+      - name: Pack the template
+        run: dotnet pack TemplatePack.csproj -c Release -o artifacts

.gitignore

@@ -0,0 +1,10 @@
+[Bb]in/
+[Oo]bj/
+.vs/
+.idea/
+*.user
+*.nupkg
+artifacts/
+TestResults/
+node_modules/
+.DS_Store

CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## [Unreleased]
+
+### 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
+
+### 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.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Code4mk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,76 @@
+# .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.
+
+```bash
+dotnet new install Code4mk.McpServer.Template
+dotnet new code4mk-mcp -n NexusRE.Mcp -o nexusre-mcp
+```
+
+## What you get
+
+| Area | Included |
+| --- | --- |
+| 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
+
+```bash
+dotnet new install Code4mk.McpServer.Template        # from nuget.org
+# or from source:
+git clone https://github.com/code4mk/dotnet-mcp-template && dotnet new install ./dotnet-mcp-template/templates/DotnetMcpTemplate
+```
+
+## 2. Create a project
+
+Run it outside this repository:
+
+```bash
+dotnet new code4mk-mcp -n NexusRE.Mcp -o nexusre-mcp
+```
+
+`-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.
+
+## 3. Run
+
+```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
+```
+
+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/`.
+
+Hidden files (`.env.example`, `.gitignore`, `.github/`, `.template.config/`) start with a dot: show hidden files
+in Finder (`Cmd+Shift+.`) or Explorer.
+
+## Repository layout
+
+```text
+dotnet-mcp-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
+```
+
+## Maintaining
+
+- 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`.

TemplatePack.csproj

@@ -0,0 +1,32 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <!-- Packs templates/DotnetMcpTemplate into a NuGet template package: dotnet pack TemplatePack.csproj -->
+  <PropertyGroup>
+    <PackageType>Template</PackageType>
+    <PackageId>Code4mk.McpServer.Template</PackageId>
+    <PackageVersion>1.0.0</PackageVersion>
+    <Title>Code4mk MCP Server</Title>
+    <Authors>Code4mk</Authors>
+    <Description>ASP.NET Core MCP server template (official C# SDK 2.0): tools, resources, prompts, MCP Apps, OIDC proxy auth for any IdP, typed API clients, validation, Docker, tests and docs.</Description>
+    <PackageTags>dotnet-new;templates;mcp;model-context-protocol;aspnetcore;oidc</PackageTags>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
+    <PackageProjectUrl>https://github.com/code4mk/dotnet-mcp-template</PackageProjectUrl>
+    <RepositoryUrl>https://github.com/code4mk/dotnet-mcp-template</RepositoryUrl>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+
+    <TargetFramework>net10.0</TargetFramework>
+    <IncludeContentInPack>true</IncludeContentInPack>
+    <IncludeBuildOutput>false</IncludeBuildOutput>
+    <ContentTargetFolders>content</ContentTargetFolders>
+    <NoDefaultExcludes>true</NoDefaultExcludes>
+    <EnableDefaultItems>false</EnableDefaultItems>
+    <NoWarn>$(NoWarn);NU5128;NU5110;NU5111</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Content Include="templates/**/*"
+             Exclude="templates/**/bin/**;templates/**/obj/**;templates/**/.vs/**;templates/**/TestResults/**;templates/**/node_modules/**" />
+    <None Include="README.md" Pack="true" PackagePath="/" />
+  </ItemGroup>
+
+</Project>

templates/DotnetMcpTemplate/.dockerignore

@@ -0,0 +1,12 @@
+**/bin/
+**/obj/
+**/.vs/
+**/.idea/
+**/TestResults/
+**/node_modules/
+.git/
+.github/
+docs/
+tests/
+.env
+.env.*

templates/DotnetMcpTemplate/.editorconfig

@@ -0,0 +1,23 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{json,yml,yaml,props,csproj,xml,ts,tsx,html,css}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.cs]
+csharp_style_namespace_declarations = file_scoped:warning
+dotnet_sort_system_directives_first = true
+csharp_style_var_for_built_in_types = true:suggestion
+csharp_style_var_when_type_is_apparent = true:suggestion
+csharp_style_prefer_primary_constructors = true:suggestion
+dotnet_style_prefer_collection_expression = true:suggestion

templates/DotnetMcpTemplate/.env.example

@@ -0,0 +1,69 @@
+# Example settings: the only env file committed to git. Copy it to start:
+#   cp .env.example .env
+# Variables already set in the environment (Docker, CI, shell) always win over .env.
+# Keep only placeholders and local-only defaults here, never real secrets.
+
+# ---------------------------------------------------------------- App
+# dev | stage | prod  (maps to Development | Staging | Production)
+APP_ENV=dev
+# Port the server listens on (also used by Docker Compose).
+APP_PORT=5080
+# Public base URL clients use (behind a proxy: https://mcp.example.com). Empty = http://localhost:${APP_PORT}
+APP_URL=
+
+# ---------------------------------------------------------------- MCP
+MCP_SERVER_NAME=DotnetMcpTemplate
+MCP_PATH=/mcp
+# Optional instructions sent to clients (what this server is for).
+MCP_INSTRUCTIONS=
+# required: every MCP request needs a token (clients log in on connect)
+# mixed:    anonymous clients can connect; [Authorize] is checked per tool/resource/prompt
+# none:     no login, a fixed developer user is signed in (only allowed when APP_ENV=dev)
+MCP_AUTH_MODE=required
+# Where built MCP App bundles live. Empty = ui_dist next to the app.
+MCP_UI_DIST_DIR=
+
+# ---------------------------------------------------------------- Auth
+# oidc (default, proxy for any OIDC identity provider) | jwt (validate IdP tokens directly) | your own provider
+AUTH_PROVIDER=oidc
+
+# --- OIDC identity provider (any IdP: Google, Entra ID, Auth0, Okta, Keycloak, Zitadel, ...)
+# Register ONE app in your IdP with redirect URI: ${APP_URL}/oauth/callback
+OIDC_DISCOVERY_URL=https://accounts.google.com/.well-known/openid-configuration
+OIDC_CLIENT_ID=change-me
+# Empty = public client (PKCE only).
+OIDC_CLIENT_SECRET=
+# client_secret_basic | client_secret_post
+OIDC_CLIENT_AUTH_METHOD=client_secret_basic
+OIDC_SCOPES=openid,profile,email
+# auto: call userinfo when the IdP advertises it | always | never
+OIDC_USERINFO=auto
+# Claim holding roles; dot paths work for nested claims, e.g. realm_access.roles
+OIDC_ROLE_CLAIM=roles
+OIDC_GROUPS_CLAIM=groups
+# Extra IdP claims to copy into the server token (comma-separated), e.g. tenant_id,department
+OIDC_TOKEN_CLAIMS=
+# jwt provider only: accepted token audience(s). Empty = the MCP URL (APP_URL + MCP_PATH).
+OIDC_AUDIENCE=
+
+# --- OIDC proxy (the MCP server is the OAuth server for MCP clients)
+# Signs server-issued tokens and encrypts stored IdP tokens. 32+ chars: openssl rand -base64 48
+AUTH_TOKEN_SIGNING_KEY=development-only-signing-key-change-me-0123456789
+AUTH_TOKEN_LIFETIME_MINUTES=60
+AUTH_REFRESH_TOKEN_LIFETIME_DAYS=30
+# Redirect URIs MCP clients may register (comma-separated; * allowed in port and path).
+AUTH_ALLOWED_REDIRECT_URIS=http://localhost:*,http://127.0.0.1:*,https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback
+# Remember a user's consent for a client for N days (0 = always ask).
+AUTH_CONSENT_REMEMBER_DAYS=30
+# memory (single instance) | redis (several instances)
+AUTH_STORE=memory
+REDIS_URL=
+
+# ---------------------------------------------------------------- API clients (one prefix per data source)
+# {PREFIX}_BASE_URL, _TIMEOUT_SECONDS, _RETRY_COUNT, _RETRY_UNSAFE_METHODS, _HEADERS,
+# _AUTH = none | bearer | api_key | basic | client_credentials | user
+SAMPLE_API_BASE_URL=https://jsonplaceholder.typicode.com/
+SAMPLE_API_TIMEOUT_SECONDS=15
+SAMPLE_API_RETRY_COUNT=3
+SAMPLE_API_AUTH=none
+SAMPLE_API_HEADERS=