Skip to content

Add file-based MCP server sample #928

@Meir017

Description

@Meir017

Description

Add a sample demonstrating the .NET 10 file-based programs feature for creating MCP servers. This would showcase how to build a complete MCP stdio server in a single .cs file without requiring a project (.csproj) file.

Motivation

File-based programs are ideal for:

  • Learning the MCP SDK with minimal overhead
  • Quick prototyping and experimentation
  • Building simple command-line utilities
  • Creating educational samples and tutorials

Currently, all samples in the repository use traditional project-based structures. A file-based sample would provide an alternative approach that's more accessible for newcomers and better suited for small, self-contained examples.

Proposed Implementation

Create samples/FileBasedMcpServer/ with a single Program.cs file that demonstrates:

Key Features

  • Top-level statements - No explicit Main method boilerplate
  • File-scoped types - Using the file keyword to keep types contained
  • Unix shebang support - #!/usr/local/share/dotnet/dotnet run for direct execution
  • Package directives - #:package for NuGet packages and #:project for local references
  • No project file - Run directly with dotnet run Program.cs

Sample Content

  • A complete MCP stdio server with hosting and DI
  • Example tools (e.g., weather forecast tools)
  • Proper logging configuration to stderr
  • File-scoped classes and records

Documentation

  • README explaining file-based programs
  • Comparison with project-based samples
  • Instructions for running on different platforms
  • Guidance on when to use file-based vs project-based approaches

Reference

Benefits

  • Lower barrier to entry for developers learning MCP
  • Demonstrates modern C# 14 features
  • Provides a lightweight alternative to full project structure
  • Great for documentation and educational purposes

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions