FSharp.MCP.DevKit 🚀

An experimental prototype of an F# development toolkit delivered via the Model Context Protocol (MCP). It provides F# Interactive (FSI) capabilities, code documentation, safe code manipulation, and analysis tools with language server features. Integration with the FAKE build system is under development.

⚠️ Disclaimer (by EHotwagner)

The project is on hold for the moment since everything is moving very fast and it makes sense to wait for things to settle down a bit and see what makes sense then. Just this july update https://code.visualstudio.com/updates/v1_103 brought tons of new features that might change the workflow considerably.

This project has been developed with significant reliance on AI-driven tools. While it has proven to be surprisingly effective—largely by leveraging robust libraries like F# Compiler Services and Fantomas—it will contain inaccuracies or incomplete features. Especially regarding Documentation, the agent tends to insert tons of industry buzzword BS whenever you look away for a second. This project has been developed with significant reliance on AI-driven tools. While it has proven to be surprisingly effective—largely by leveraging robust libraries like F# Compiler Services and Fantomas—it will contain inaccuracies or incomplete features. Especially regarding Documentation, the agent tends to insert tons of industry buzzword BS whenever you look away for a second.

Please Note

Please Note

• Code Verification: The entire codebase and its documentation have not been manually verified for correctness or completeness. However, the core features described should be functional (as in I have seen them work at least once).

• Agent Stability: The AI agent's instructions are generally initially effective, but after it deviates, restarting the agent to reset its context is recommended.

• DevEnvironment: This project has been developed in VSCode with GH Copilot, mostly using Claude Sonnet 4 and a bit of Gemini 2.5 Pro for planning and design. https://austen.info/blog/github-copilot-agent-mcp/

• DevEnvironment: This project has been developed in VSCode with GH Copilot, mostly using Claude Sonnet 4 and a bit of Gemini 2.5 Pro for planning and design. https://austen.info/blog/github-copilot-agent-mcp/

• Design: Documentation is written somewhat with REPL-driven development in mind, allowing for interactive code generation and testing. I am currently tending towards a more script-driven development approach, which allows for structured experimentation and reproducible testing. A new, more rigorous approach, Signature-Driven Development, is also being considered.

  • REPL-Driven Development
  • Script-Driven Development
  • Signature-Driven Development

• REPL works with hosted FSI sessions, which in this context are not easy to configure, a bit fragile with some Input, have no nice output (only MCP-Tools output terminal and agent chat window). Letting the agent start a standard fsi process in an agent observed terminal is of course possible but cumbersome in VSCode since terminal actions need approval. This project should be neutral to the chosen approach in the future. VsCode Insiders has microsoft/vscode#253103 which changes the ergonomics a lot. Needs consideration.

• Get Started: There are no releases yet. For VSCode use this https://devblogs.microsoft.com/dotnet/build-a-model-context-protocol-mcp-server-in-csharp/ approach. Add the project to the mcp.json file. Later a dotnet tool might be the best way to distribute this project.

✨ Features

🔧 F# Interactive Integration

• Persistent FSI Session: Stateful F# Interactive session management
• Code Execution: Execute F# code with comprehensive error handling and validation
• Script Loading: Load and manage F# script files with dependency tracking
• Package Management: Reference .NET assemblies and NuGet packages seamlessly
• Expression Evaluation: Evaluate F# expressions with full type information

📚 Documentation Generation & Search

• 📦 Package Documentation: Generate comprehensive API docs for NuGet packages
• 🔍 Smart Search: Search through generated documentation with context-aware results
• 📖 API Reference: Create structured markdown documentation for modules and types
• 🏗️ Project Documentation: Bulk documentation generation for entire F# projects
• 💾 Package Discovery: Browse and explore available NuGet packages in local cache
• ⚙️ Configuration Management: Runtime configuration of documentation settings

✏️ Safe Code Manipulation

• 🛡️ Safe Code Insertion: Insert F# code with AST validation and type checking
• 🎨 Code Formatting: Deep integration with Fantomas for consistent code formatting
• 🔍 Structure Analysis: Analyze F# code structure, dependencies, and syntax
• 👀 Preview Capabilities: Preview code changes before applying them
• ⚡ Atomic Operations: Atomic file operations with backup/rollback support

🧠 Advanced Analysis Tools

• 🔍 Symbol Detection: Advanced symbol detection and resolution

  • Powered by: SmartSymbolDetectionService - Uses F# Compiler Services to identify and resolve symbols, functions, types, and modules within F# code
  • How it works: Parses source code into AST, performs semantic analysis to resolve symbol bindings, their scope, and provides position-sensitive symbol lookup
  • MCP Tools: GetAllSymbols, GetSymbolAtPosition, WhatIsAtPosition, GetSymbolSignatureAtPosition

• 📊 Syntax Validation: Comprehensive F# syntax analysis and error reporting

  • Powered by: ParseAndCheckFSharpCode - Validates F# syntax and performs type checking with detailed diagnostics
  • How it works: Uses F# Compiler Services via IPC to parse source code, check for syntax errors, type mismatches, and compiler warnings with line-level error locations

• 🗂️ Dependency Analysis: Track and analyze code dependencies and relationships

  • Powered by: AnalyzeCodeStructure - Provides basic file analysis including line count, character count, and diagnostic summaries
  • How it works: Performs F# Compiler Services parsing to identify errors, warnings, and structural issues in F# files
  • Current scope: File-level analysis rather than deep dependency graph analysis

• 🎯 Position-Sensitive Analysis: Context-aware code analysis based on cursor position

🏗️ Architecture

The FSharp.MCP.DevKit follows a modular, layered architecture with clear separation of concerns:

├── 🔧 FSharp.MCP.DevKit.Core/          # Foundation layer
│   ├── FSI session management & execution
│   ├── File system utilities & helpers  
│   └── Core types & configurations
│
├── 🔍 FSharp.MCP.DevKit.Analysis/      # Code intelligence layer
│   ├── F# syntax validation & analysis
│   ├── Symbol detection & resolution
│   └── Code structure analysis
│
├── 📡 FSharp.MCP.DevKit.Communication/ # IPC infrastructure
│   ├── High-performance named pipes
│   └── Persistent REPL server
│
├── ✏️ FSharp.MCP.DevKit.CodeEditing/   # Code manipulation layer
│   ├── Safe code insertion & editing
│   ├── Fantomas formatting integration
│   └── Atomic file operations
│
├── 📚 FSharp.MCP.DevKit.Documentation/ # Documentation generation
│   ├── .NET assembly analysis
│   ├── NuGet package documentation
│   └── Markdown API reference generation
│
└── 🌐 FSharp.MCP.DevKit.Server/        # MCP server & tools
    ├── MCP protocol implementation
    ├── 30+ specialized F# tools
    └── Server runtime & hosting

🔄 Data Flow Architecture

graph TB
    subgraph "🤖 AI Assistant Layer"
        Assistant["`**AI Assistant**
        (Claude, GPT, etc.)
        • F# Development Support
        • Code Generation
        • Interactive Analysis`"]
    end
    
    subgraph "📡 MCP Protocol Layer"
        MCPServer["`**MCP Server**
        • 30+ F# Tools
        • Stdio Transport
        • JSON-RPC Protocol`"]
    end
    
    subgraph "🌐 Application Layer"
        Server["`**FSharp.MCP.DevKit.Server**
        • Tool Implementation
        • Request Routing
        • Error Handling`"]
    end
    
    subgraph "🛠️ Service Layers"
        Documentation["`**📚 Documentation**
        • Package Documentation
        • API Reference Generation
        • Smart Search & Discovery`"]
        
        DocumentationTool["`**🔧 Documentation Tool**
        • CLI for Doc Generation`"]

        CodeEditing["`**✏️ Code Editing**
        • Safe Code Insertion
        • Fantomas Integration
        • Atomic Operations`"]
        
        Communication["`**📡 Communication**
        • Named Pipes IPC
        • Concurrent Processing
        • REPL Server`"]
        
        Analysis["`**🔍 Analysis**
        • Symbol Detection
        • Syntax Validation
        • Structure Analysis`"]
    end
    
    subgraph "🔧 Foundation Layer"
        Core["`**FSharp.MCP.DevKit.Core**
        • FSI Session Management
        • File Operations
        • Configuration`"]
    end
    
    subgraph "🔗 External Dependencies"
        FCS["`**F# Compiler Services**
        • Code Compilation
        • Type Checking
        • AST Analysis`"]
        
        Fantomas["`**Fantomas**
        • Code Formatting
        • Style Enforcement`"]
        
        FSI["`**F# Interactive**
        • Code Execution
        • REPL Environment`"]
    end
    
    %% Connections
    Assistant <--> MCPServer
    MCPServer <--> Server
    Server --> Documentation
    Server --> CodeEditing
    Server --> Communication
    Server --> Analysis
    Documentation --> Core
    DocumentationTool --> Documentation
    CodeEditing --> Core
    Communication --> Core
    Analysis --> Core
    
    %% External integrations
    Core --> FCS
    Core --> FSI
    CodeEditing --> Fantomas
    Analysis --> FCS
    Documentation --> FCS
    
    %% Styling
    classDef aiLayer fill:#4B0082,stroke:#ffffff,stroke-width:3px,color:#ffffff
    classDef mcpLayer fill:#8B0000,stroke:#ffffff,stroke-width:2px,color:#ffffff
    classDef appLayer fill:#000080,stroke:#ffffff,stroke-width:2px,color:#ffffff
    classDef serviceLayer fill:#006400,stroke:#ffffff,stroke-width:2px,color:#ffffff
    classDef foundationLayer fill:#2F4F4F,stroke:#ffffff,stroke-width:2px,color:#ffffff
    classDef externalDep fill:#FF8C00,stroke:#000000,stroke-width:2px,color:#000000
    
    class Assistant aiLayer
    class MCPServer mcpLayer
    class Server appLayer
    class Documentation,CodeEditing,Communication,Analysis,DocumentationTool serviceLayer
    class Core foundationLayer
    class FCS,Fantomas,FSI externalDep

Loading

🛠️ MCP Tools Overview

The server provides 30+ specialized MCP tools organized into categories:

📚 Documentation Tools (New!)

• GeneratePackageDocumentation - Generate comprehensive API docs for NuGet packages
• GenerateProjectDocumentation - Bulk documentation for entire F# projects
• SearchDocumentation - Search through generated documentation with context
• ListCachedPackages - Browse available NuGet packages in local cache
• ShowPackageInfo - Get detailed information about specific packages
• SetDocumentationOutputDirectory - Configure documentation output settings
• ShowDocumentationConfig - Display current documentation configuration

🔧 FSI Management

• CheckFSIServerStatus - Check FSI server status and availability
• ResetFSISession - Reset the FSI session clearing all state
• RestartFSISession - Restart FSI session (stop and start fresh)
• GetFSIState - Get current FSI state and bindings

⚡ Code Execution

• ExecuteFSharpCode - Execute F# code with comprehensive error handling
• ExecuteFSharpCodeDetailed - Execute with detailed error information
• EvaluateFSharpExpression - Evaluate expressions with type information
• LoadFSharpScript - Load F# script files with dependency tracking
• ReferenceAssembly - Reference .NET assemblies
• ReferenceNuGetPackage - Reference NuGet packages dynamically
• AddSearchPath - Add directories to F# search path

✏️ Code Manipulation & File Operations

• InsertCode - Unified code insertion with validation and formatting
• PreviewCodeInjection - Preview code changes before applying
• FormatFile - Format entire F# files using Fantomas
• DeleteLines - Delete specific lines from files
• ReplaceTextRange - Replace text in specific line ranges
• SearchAndReplace - Search and replace with pattern matching
• MoveCodeBlock - Move code blocks between locations
• GetLines - Extract specific lines for inspection
• CountLines - Count lines and characters in files
• SearchInFile - Search for patterns with line numbers

🔍 Analysis & Structure

• AnalyzeCodeStructure - Analyze F# code structure and dependencies
• ParseAndCheckFSharpCode - Parse and validate F# syntax and types
• ParseSourceToAST - Parse code to Abstract Syntax Tree

🛠️ Utility & Management

• KillAll - Kill all MCP server processes for clean restarts (temporary till FAKE integration)

🚀 Usage Examples

Documentation Generation

# Generate documentation for a NuGet package
GeneratePackageDocumentation "System.Text.Json" "./docs" true

# Search through generated documentation  
SearchDocumentation "./docs" "JsonSerializer"

# List available packages
ListCachedPackages "System"

Code Execution

// Execute F# code
ExecuteFSharpCode "let x = 1 + 2; printfn \"Result: %d\" x"

// Evaluate expressions with type info
EvaluateFSharpExpression "List.map ((*) 2) [1..5]"

// Reference packages
ReferenceNuGetPackage "FSharp.Data"

Safe Code Insertion

// Insert code with formatting, validation disabled by default for performance
InsertCode "let newFunction x = x * 2" "MyScript.fsx" 10 1 true false

// Enable validation for small, critical code pieces  
InsertCode "let helper = x + 1" "MyScript.fsx" 5 1 true true

// Preview changes first
PreviewCodeInjection "let helper = ..." "MyScript.fsx" 15

🤖 Agent Development Strategies

This project provides comprehensive strategies for AI agents to work effectively with F# development through different methodologies:

📋 Available Development Approaches

The toolkit supports multiple development philosophies, each optimized for different scenarios and agent capabilities:

🎯 Script-Driven Development

Recommended for: Production workflows, complex validation, agent-driven development

• 📖 Design Philosophy - Comprehensive guide to script-based development methodology
• 🛠️ Copilot Instructions - Detailed agent instructions for script-driven workflows
• Key Characteristics: Reproducible execution, structured output, comprehensive validation, audit trails

🔄 REPL-Driven Development

Recommended for: Exploration, prototyping, interactive development

• 📖 Design Philosophy - Deep dive into REPL-based development patterns
• 🛠️ Copilot Instructions - Agent guidance for interactive REPL workflows
• Key Characteristics: Immediate feedback, live debugging, exploratory programming, state preservation

📜 Signature-Driven Development

Recommended for: Contract-first development, rigorous validation, clear interfaces

• 📖 Design Philosophy - In-depth exploration of signature-driven development principles
• 🛠️ Copilot Instructions - Instructions for implementing signature-driven workflows
• Key Characteristics: Explicit contracts, enhanced validation, clear module boundaries, improved collaboration

📜 Signature-Driven Development

Recommended for: Contract-first development, rigorous validation, clear interfaces

• 📖 Design Philosophy - In-depth exploration of signature-driven development principles
• 🛠️ Copilot Instructions - Instructions for implementing signature-driven workflows
• Key Characteristics: Explicit contracts, enhanced validation, clear module boundaries, improved collaboration

📖 Documentation

📂 Project Documentation

Comprehensive documentation organized by project:

• 📚 All Projects Documentation - Complete documentation index
• 🔧 Core - Foundation layer documentation
• 🔍 Analysis - Code analysis and intelligence
• 📡 Communication - IPC infrastructure
• ✏️ CodeEditing - Code manipulation capabilities
• 🌐 Server - MCP server implementation
• 📚 Documentation - Documentation generation

📋 General Documentation

• 🏗️ Architecture - System design and architecture
• ✨ Features - Detailed feature documentation
• 🎯 Terminal Code Execution - Multi-terminal F# execution and session targeting
• 🎯 Terminal Code Execution - Proposal for Multi-terminal F# execution and session targeting
• 📝 Design & Analysis - Design decisions and analysis
• 📋 Implementation Summary - Implementation details
• 🗂️ Plans & Specifications - Development roadmaps

�️ Development Roadmap

🎯 Near-term Enhancements

🔄 Currently In Progress:

• 📚 Cross-reference linking - Automatic linking between types in documentation (maybe https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode )
• Fake Integration
• Planning Tools - Adding some deterministic planning tools and Knowledge bases to help the AI agent generate more structured code.
• Increase performance and robustness of text, file handling and code insertion.

�🔗 Key Technologies

• F# Compiler Services - F# language analysis and compilation
• Fantomas - F# code formatting
• Model Context Protocol - AI assistant integration protocol
• Named Pipes - High-performance inter-process communication
• .NET 9.0 - Modern .NET runtime and libraries

For current development status and known issues, see:

• 🐛 Known Issues - Current bugs and limitations

� Communication & Contact

We welcome your feedback, questions, and contributions! Here's how to get in touch:

🎮 Discord Community

Join the F# community discussions:

• F# Discord - #tools-and-libraries - Get help, share ideas, and discuss F# tooling

🐛 Issues & Bug Reports

Found a bug or have a feature request?

• GitHub Issues - Report bugs, request features, or ask questions

�📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Resources

• Build a Model Context Protocol Server in C# - Microsoft DevBlogs guide
• Model Context Protocol Documentation - Official MCP documentation
• F# Documentation - Official F# documentation

---

📚 Documentation • 🛠️ Tools • 🏗️ Architecture

Built with ❤️ using F# and the Model Context Protocol