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

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions