# NuGet Package Type Reference

Structural requirements for each NuGet package type. The agent uses this to validate a repo's packaging setup before configuring trusted publishing.

## Detection Logic

Inspect `.csproj` files (and `Directory.Build.props` if present) for these MSBuild properties:

```
1. Has <PackageType>Template</PackageType>?           → Template package
2. Has <PackageType>McpServer</PackageType>?           → MCP server (also a dotnet tool)
3. Has <PackAsTool>true</PackAsTool>?                  → Dotnet tool
4. Has <IsPackable>true</IsPackable> or no OutputType? → NuGet library
5. Has <OutputType>Exe</OutputType> + <IsPackable>true</IsPackable>? → Application package
6. Has <OutputType>Exe</OutputType> without PackAsTool or IsPackable? → Not packable by default (ask user)
```

Check in order — MCP servers have `PackAsTool` too, so `PackageType` must be checked first.

## NuGet Library

The most common case. A class library consumed via `PackageReference`.

### Required Properties

| Property | Example | Notes |
|----------|---------|-------|
| `PackageId` | `Contoso.Utilities` | Defaults to `AssemblyName` if omitted |
| `Version` | `0.1.0` | Start with 0.x for initial development |

### Recommended Properties

| Property | Purpose |
|----------|---------|
| `Authors` | Package author(s) |
| `Description` | Shown on nuget.org |
| `PackageTags` | Discoverability |
| `PackageReadmeFile` | README displayed on nuget.org |
| `PackageLicenseExpression` | SPDX license identifier |
| `RepositoryUrl` | Link back to source |
| `PublishRepositoryUrl` | Enables source-link integration |

### Including README in Package

`PackageReadmeFile` alone isn't enough — you must also include the file in the package:

```xml
<PropertyGroup>
  <PackageReadmeFile>README.md</PackageReadmeFile>
</PropertyGroup>
<ItemGroup>
  <None Include="README.md" Pack="true" PackagePath="/" />
  <!-- If README is in a parent dir (common for src/ layouts): -->
  <!-- <None Include="../../README.md" Pack="true" PackagePath="/" /> -->
</ItemGroup>
```

### Minimal .csproj

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <PackageId>Contoso.Utilities</PackageId>
    <Version>0.1.0</Version>
    <Authors>Contoso</Authors>
    <Description>Utility library for Contoso apps</Description>
    <PackageReadmeFile>README.md</PackageReadmeFile>
  </PropertyGroup>
  <ItemGroup>
    <None Include="README.md" Pack="true" PackagePath="/" />
  </ItemGroup>
</Project>
```

### Pack Command

```bash
dotnet pack -c Release
```

## Dotnet Tool

A console app distributed as a global or local tool via `dotnet tool install`.

### Required Properties

| Property | Example | Notes |
|----------|---------|-------|
| `OutputType` | `Exe` | Must be an executable |
| `PackAsTool` | `true` | Marks this as a tool package |
| `PackageId` | `contoso-cli` | Tool package identifier |
| `Version` | `0.1.0` | Package version (or set in Directory.Build.props) |

### Recommended Properties

| Property | Example | Notes |
|----------|---------|-------|
| `ToolCommandName` | `contoso` | Command users type; defaults to assembly name |
| `PackageOutputPath` | `./nupkg` | Where .nupkg is written |
| `PackageReadmeFile` | `README.md` | Shown on nuget.org |

### Minimal .csproj

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <PackAsTool>true</PackAsTool>
    <ToolCommandName>contoso</ToolCommandName>
    <PackageId>contoso-cli</PackageId>
    <PackageReadmeFile>README.md</PackageReadmeFile>
  </PropertyGroup>
  <ItemGroup>
    <None Include="README.md" Pack="true" PackagePath="/" />
  </ItemGroup>
</Project>
```

### Pack Command

```bash
dotnet pack -c Release
```

## MCP Server

A dotnet tool that implements the Model Context Protocol. Distributed the same way as a dotnet tool but with additional metadata for MCP client discovery.

### Naming Convention

Follow the established pattern for MCP server packages:
- **PackageId**: `{github-username}.{domain}.mcp` (e.g., `lewing.helix.mcp`)
- **server.json `name`**: `io.github.{username}/{packageid}` (e.g., `io.github.lewing/lewing.helix.mcp`)

### Required Properties

Everything from Dotnet Tool, plus:

| Property | Example | Notes |
|----------|---------|-------|
| `PackageType` | `McpServer` | NuGet recognizes this as an MCP server |

### Recommended Properties

| Property | Example | Notes |
|----------|---------|-------|
| `McpServerJsonTemplateFile` | `.mcp/server.json` | MCP client discovery metadata |

### Required Files

| File | Purpose |
|------|---------|
| `.mcp/server.json` | MCP server descriptor for client discovery |

The `.mcp/server.json` must be included in the package:

```xml
<ItemGroup>
  <None Include=".mcp/server.json" Pack="true" PackagePath="/.mcp/" />
</ItemGroup>
```

### Minimal server.json

```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
  "name": "io.github.contoso/contoso.services.mcp",
  "description": "MCP server for Contoso services",
  "version": "0.1.0",
  "packages": [
    {
      "registryType": "nuget",
      "registryBaseUrl": "https://api.nuget.org",
      "identifier": "contoso.services.mcp",
      "version": "0.1.0",
      "transport": { "type": "stdio" }
    }
  ]
}
```

> ⚠️ **Version sync**: The `version` fields in `server.json` MUST match the `<Version>` in your `.csproj`. Update both when bumping versions.

> ⚠️ **nuget.org MCP Server tab**: nuget.org auto-generates MCP install config from your `server.json`. If your tool requires a subcommand (e.g., `my-tool mcp`), the generated config may omit it. Ensure your tool defaults to MCP server mode when invoked with no arguments, or uses a `--yes` flag for non-interactive acceptance.

### Minimal .csproj

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <PackAsTool>true</PackAsTool>
    <PackageType>McpServer</PackageType>
    <PackageId>contoso.services.mcp</PackageId>
    <ToolCommandName>contoso-mcp</ToolCommandName>
    <McpServerJsonTemplateFile>.mcp/server.json</McpServerJsonTemplateFile>
    <PackageReadmeFile>README.md</PackageReadmeFile>
  </PropertyGroup>
  <ItemGroup>
    <None Include=".mcp/server.json" Pack="true" PackagePath="/.mcp/" />
    <None Include="README.md" Pack="true" PackagePath="/" />
  </ItemGroup>
</Project>
```

## Template Package

A package containing `dotnet new` templates.

### Required Properties

| Property | Example | Notes |
|----------|---------|-------|
| `PackageType` | `Template` | NuGet recognizes this as a template package |
| `PackageId` | `Contoso.Templates` | Template package identifier |

### Required Files

| File | Purpose |
|------|---------|
| `content/*/.template.config/template.json` | Template definition — one per template |

The `template.json` must include at minimum: `identity`, `name`, `shortName`, `tags.type` (`item` or `project`).

### Minimal .csproj

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageType>Template</PackageType>
    <PackageId>Contoso.Templates</PackageId>
    <Version>0.1.0</Version>
    <Description>Contoso project templates</Description>

    <!-- Template packages should not build code -->
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoDefaultExcludes>true</NoDefaultExcludes>
  </PropertyGroup>
  <ItemGroup>
    <Content Include="content/**" />
  </ItemGroup>
</Project>
```

## Common Gotchas

- **`IsPackable` defaults**: Class libraries default to `true`, console apps to `false`. Console apps can still be published as NuGet packages by setting `<IsPackable>true</IsPackable>` — they just won't be installable via `dotnet tool install` unless `PackAsTool` is also set.
- **`Directory.Build.props`**: Package metadata may be set at the repo root — always check there too.
- **Multi-project repos**: A repo may contain multiple packable projects of different types. Each needs its own trusted publishing workflow or a matrix build.
- **`GeneratePackageOnBuild`**: If `true`, `dotnet build` also produces the `.nupkg`. The workflow should use `dotnet pack` explicitly for clarity.

# Publish Workflow Template

Complete tag-triggered GitHub Actions workflow for publishing NuGet packages with trusted publishing. Copy and adapt to your repo.

## Template

```yaml
name: Publish to NuGet

on:
  push:
    tags:
      - 'v*'  # Triggers on version tags: v1.0.0, v1.2.3-preview.1, etc.

jobs:
  publish:
    runs-on: ubuntu-latest
    environment: release  # Uses release environment for secret scoping + protection rules
    permissions:
      id-token: write     # Required for OIDC token (NuGet trusted publishing)
      contents: read

    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '9.0.x'  # Adjust to your target framework

      - name: Extract version from tag
        id: version
        run: echo "VERSION=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT

      - name: Validate version matches project
        run: |
          PROJECT_VERSION=$(sed -n 's:.*<Version>\(.*\)</Version>.*:\1:p' path/to/YourProject.csproj)
          if [ "$PROJECT_VERSION" != "${{ steps.version.outputs.VERSION }}" ]; then
            echo "::error::Tag version (${{ steps.version.outputs.VERSION }}) doesn't match project version ($PROJECT_VERSION)"
            exit 1
          fi

      - name: Pack
        run: dotnet pack path/to/YourProject.csproj -c Release -o ./artifacts

      - name: NuGet login (OIDC)
        id: login
        uses: NuGet/login@v1
        with:
          user: ${{ secrets.NUGET_USER }}  # nuget.org profile name (NOT email)

      - name: Push to NuGet
        run: dotnet nuget push ./artifacts/*.nupkg --api-key ${{ steps.login.outputs.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate
```

## Customization Points

| Item | What to change |
|------|---------------|
| `dotnet-version` | Match your `TargetFramework` |
| `path/to/YourProject.csproj` | Path to your packable project |
| Version extraction `sed` | Adjust for `Directory.Build.props` or .NET 10 file-based apps (`#:property Version=`) |
| `--skip-duplicate` | Keeps push idempotent — safe for re-runs and matrix builds |

## Release Process

Once the workflow is committed, the publish process is:

```bash
# 1. Bump version in .csproj (and server.json for MCP servers)
# 2. Commit
git add -A && git commit -m "Bump version to 0.1.0"
# 3. Tag and push
git tag v0.1.0
git push origin main --tags
# 4. Workflow runs automatically, publishes to nuget.org
```

## Optional: GitHub Release Step

Add after the push step if you want GitHub Releases with the `.nupkg` attached. Note: this requires changing `contents: read` to `contents: write` in the job permissions.

```yaml
      - name: Create GitHub Release
        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2
        with:
          files: ./artifacts/*.nupkg
          generate_release_notes: true
```

> ⚠️ **Consider omitting this step entirely.** Creating GitHub Releases separately (manually or via `gh release create` in a different workflow) avoids 422 `already_exists` conflicts and keeps the publish workflow focused on NuGet. If any release step fails, it blocks NuGet publishing too.

> ⚠️ **Don't use `ncipollo/release-action` AND `gh release create` for the same tag** — this causes HTTP 422 `already_exists` errors.

> ⚠️ **`gh run rerun` replays the original YAML** from the tag commit, not from `main`. If the workflow fails due to a release conflict, delete the conflicting release and re-run — don't delete the tag and re-tag (NuGet package IDs are permanent).

## CI vs Publish Separation

Keep your CI workflow (build + test on PR/push) separate from the publish workflow (tag-triggered). This gives you:
- CI runs on every PR without publishing
- Publish only runs on deliberate version tags
- Different permission scopes (CI doesn't need `id-token: write`)