FsLangMCP (F# + FsMcp + FsAutoComplete + FCS)

An MCP server written in F# that combines:

• fsautocomplete (LSP bridge for editor-like features)
• FSharp.Compiler.Service (compiler-semantic features for AI workflows)

Work in progress: APIs and tool shapes may still change.

Changelog

See CHANGELOG.md for the full release history.

Response Shape

All tools return a consistent JSON envelope:

• Success: {"status": "ok", "result": <payload>} (LSP tools) or {"status": "ok", ...fields} (FCS tools)
• Not ready: {"status": "not_ready", "message": "..."} — LSP workspace still loading
• Error: MCP protocol error with {"errorKind": "...", "message": "..."} payload

What You Get

LSP-proxy tools (via fsautocomplete)

• textDocument_completion
• textDocument_definition
• textDocument_references
• textDocument_formatting — format F# file via Fantomas (via fsautocomplete)
• textDocument_codeAction — available code actions / quick fixes at cursor
• textDocument_rename — rename a symbol across the project
• workspace_symbol
• workspace_diagnostics (cache of latest publishDiagnostics)
• fsharp_signature_data — structured FSAC signature help at an exact position
• set_project (switch active project/workspace for LSP context)

LSP positions (line, character) are 0-based.

The textDocument_* and workspace_* tools are raw LSP/IDE-shaped proxies. They are useful for exact-position editor operations and FSAC debugging. Prefer the FCS tools and project_health for agent-friendly project understanding.

FCS tools (compiler semantics)

• fcs_parse_and_check_file
• fcs_file_outline — compact per-file API/navigation outline for agents
• fcs_project_outline — compact project-wide outline over filtered compile files
• fcs_find_symbol — grouped definitions/references with source context
• fcs_symbol_at_word — tolerant symbol lookup by line + word/occurrence
• fcs_file_symbols
• fcs_project_symbol_uses
• fcs_type_at_position — inferred F# type and symbol info at cursor (works without LSP workspace)
• fcs_signature_help — method overloads and parameter info at cursor
• fcs_get_project_options — get OtherOptions for a .fsproj via proj-info; use the result as projectOptions in other FCS tools

Project preflight

• fsharp_project_inspect — read-only .fsproj inspection: compile order, references, source summary, and signature/implementation pairing.
• project_health — fast read-only project preflight. Reports project options availability, source file readability, analyzer setup, test project discovery, and current LSP readiness. It does not start/switch FSAC, run compile, or run tests.
• fsharp_compile — FCS project validation. Loads .fsproj options through Ionide.ProjInfo, then runs FSharpChecker.ParseAndCheckProject. It does not require set_project, run dotnet build, emit assemblies, or run tests.

Prerequisites

• .NET SDK 10+
• fsautocomplete installed
• ionide.projinfo.tool (required for fcs_get_project_options)

Install fsautocomplete:

dotnet tool install -g fsautocomplete

Install ionide.projinfo.tool:

dotnet tool install -g ionide.projinfo.tool

For local development of this repository, restore the local analyzer tool:

dotnet tool restore

Install As Dotnet Tool

From NuGet (recommended)

dotnet tool install -g FsLangMcp
fslangmcp --bootstrap-tools

Update later with dotnet tool update -g FsLangMcp.

From source (developing FsLangMCP itself)

dotnet pack -c Release
dotnet tool install -g --add-source ./nupkg FsLangMcp
fslangmcp --bootstrap-tools

After install, command is:

fslangmcp

Runtime Options

Pass paths as command args (recommended):

• --project <path-to-fsproj> or -p <path-to-fsproj>
• --fsac-command <cmd> (optional override)
• --fsac-args "<args>" (optional override)
• --bootstrap-tools (install/update fsautocomplete and ionide.projinfo.tool)

Environment fallbacks still work:

• FSAC_COMMAND
• FSAC_ARGS
• FSA_PROJECT_PATH

Garbage collector — tuned for stdio servers

FsLangMCP ships with Workstation GC + Concurrent GC baked in via runtimeconfig.template.json. This is the recommended profile for stdio MCP servers per FsMcp's runtime tuning guide: an FCS workload is bursty (load → idle → next request), and Server GC's "don't release until OS pressure" produces alarming RSS growth on dev laptops that won't trigger pressure events.

Operators can override at the env-var level if needed (env always wins over runtimeconfig):

• DOTNET_gcServer=1 — opt back into Server GC (higher throughput, holds memory longer)
• DOTNET_GCHeapHardLimitPercent=0xA — cap heap at 10% of RAM (works with either GC mode)

MCP Stdio Config (Installed Tool)

{
  "mcpServers": {
    "fsharp": {
      "command": "fslangmcp",
      "args": ["--project", "/absolute/path/to/App.fsproj"],
      "env": {
        "FSAC_COMMAND": "fsautocomplete"
      }
    }
  }
}

Parallel Agent Usage

For multiple agents sharing one FsLangMCP server, prefer the FCS tools and pass projectPath on every request:

{
  "path": "/absolute/path/to/File.fs",
  "projectPath": "/absolute/path/to/App.fsproj"
}

FCS tools resolve compiler options per project and cache project-wide results by the resolved .fsproj, so agents working on different projects do not share stale symbol caches. The server also limits expensive work by default:

• FSLANGMCP_MAX_CONCURRENT_FCS=2
• FSLANGMCP_MAX_CONCURRENT_LSP=1

The LSP-proxy tools use one fsautocomplete workspace per server process. They are serialized to avoid corrupting the active document/workspace state, but they are not intended for independent parallel workspaces in the same MCP process.

Example Agent Session

Start by selecting a project:

{
  "projectPath": "/absolute/path/to/App.fsproj",
  "workspacePath": null,
  "restartLsp": true
}

Then ask for a health report:

{
  "projectPath": "/absolute/path/to/App.fsproj",
  "workspacePath": null,
  "scope": null,
  "compileCheck": null
}

Typical next calls:

• fcs_parse_and_check_file with projectPath for one file.
• fcs_file_outline for a compact map of a file.
• fcs_find_symbol when you need definitions/references plus source context.
• fcs_symbol_at_word when you know the line and word but not the exact cursor column.
• fcs_project_symbol_uses with symbolQuery for project-wide references.
• workspace_diagnostics to inspect current FSAC/compiler/analyzer diagnostics.
• fsharp_compile for project-wide FCS parse+typecheck validation.

For repeated multi-agent use, pass projectPath directly to FCS tools instead of relying on mutable LSP workspace state.

Development Commands

just restore
just check
just analyze

• just check runs build + tests.
• just analyze runs F# analyzers through FSharp.Analyzers.Build.

The repository currently wires:

• Ionide.Analyzers
• G-Research.FSharp.Analyzers
• FSharp.Analyzers.Build
• local fsharp-analyzers tool

MCP Stdio Config (Local Dev Without Install)

{
  "mcpServers": {
    "fsharp": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "/path/to/FsLangMcp.fsproj",
        "--",
        "--project",
        "/absolute/path/to/App.fsproj"
      ],
      "env": {
        "FSAC_COMMAND": "fsautocomplete"
      }
    }
  }
}

How To Get projectOptions For FCS Tools

For accurate .fsproj / .sln / .slnx context, use ionide/proj-info:

dotnet tool install -g ionide.projinfo.tool
proj-info --project /absolute/path/to/App.fsproj --fcs --serialize

Use OtherOptions from the emitted JSON as projectOptions in:

• fcs_parse_and_check_file
• fcs_file_symbols
• fcs_project_symbol_uses

If both projectPath and projectOptions are omitted, the server first tries to auto-discover the nearest .fsproj. If no project can be found, it falls back to script-style inference (GetProjectOptionsFromScript), which is less accurate for large multi-project solutions.

set_project Tool

Use this MCP tool to switch active project context without restarting the MCP process.

Input shape:

{
  "projectPath": "/absolute/path/to/App.fsproj",
  "workspacePath": null,
  "restartLsp": true
}

restartLsp defaults to true so the new context is applied immediately.

project_health Tool

Use project_health before deeper semantic work when you need to know whether FsLangMCP can trust the project state.

Input shape:

{
  "projectPath": "/absolute/path/to/App.fsproj",
  "workspacePath": null,
  "scope": null,
  "compileCheck": null
}

Notes:

• v0.3 expects an explicit .fsproj path or a directory with exactly one .fsproj.
• Missing analyzers are reported as capability information, not as a health failure.
• Compile status is separate from tooling readiness.
• project_health does not run build or tests.

fsharp_compile Tool

Use fsharp_compile when you want read-only project-wide FCS validation without running dotnet build.

Input shape:

{
  "projectPath": "/absolute/path/to/App.fsproj",
  "workspacePath": null,
  "timeoutMs": 60000
}

fsharp_compile returns a compact status, diagnostic counts, and FCS diagnostics. It uses FSharpChecker.ParseAndCheckProject, so it checks parse/typecheck errors across the project, but it does not execute the full MSBuild build pipeline, emit an assembly, or run tests.

Known Issues

• LSP proxy tools return {"status": "not_ready"} if called before fsautocomplete has finished loading the project. set_project waits up to 30 seconds — if you still get not_ready, the project may be too large or fsautocomplete may have failed to start.
• project_health v0.3 is intentionally project-focused. It does not yet inspect whole solutions or resolve ambiguous directories.
• FCS tools fall back to script-style inference (GetProjectOptionsFromScript) only when neither projectPath nor an auto-discovered .fsproj is available. In that mode, diagnostics and symbol data can be incomplete for multi-project solutions.
• fcs_project_symbol_uses results are cached per project. Call set_project to flush the cache when source files change on disk.

About Tool Dependencies

dotnet tool packages cannot automatically install other global tools during installation. This project provides:

• fslangmcp --bootstrap-tools

It runs dotnet tool update -g ... (or install if missing) for:

• fsautocomplete
• ionide.projinfo.tool