Fortran MCP

Fortran MCP gives AI tools a compact, cited reference for modern and legacy Fortran development. Its local corpus covers language and compiler behavior, builds, preprocessing, interoperability, parallel programming, correctness, modernization, and ecosystem discovery without requiring a hosted search service.

Install

Prerequisite: Python 3.11+ and uv.

uv tool install fortran-mcp

Configure an MCP client to launch the stdio command fortran-mcp; see Connect an MCP client for examples. When fortran-mcp starts in a terminal with no data installed, it reports that no data packages were found and offers to install core for lexical search or core plus semantic for semantic and hybrid search; the download only starts after a choice. Skipping, or a failed download, prints the manual install commands and exits cleanly. Client-launched servers cannot prompt, so they download the core bundle automatically (set FORTRAN_MCP_AUTO_INSTALL=0 to manage data yourself, or FORTRAN_MCP_CATALOG to install from a local catalog path or HTTPS URL) and exit with the error and manual commands if the download fails. The optional semantic bundle and runtime are not needed for the default lexical search.

Command reference

data remove requires a package, refuses to remove core while semantic is installed, and only deletes files the remaining packages no longer need.

After connecting a client, try: “How do I add OpenMP to an fpm project? Use the Fortran documentation server and cite the source.”

Development

Prerequisites: Git and uv.

git clone https://github.com/minhqdao/fortran-mcp.git
cd fortran-mcp
uv sync
uv run fortran-mcp

uv sync creates .venv and installs the locked runtime and development dependencies. The server uses the standard input/output transport by default. For local HTTP testing, run:

uv run fortran-mcp --transport streamable-http

The Streamable HTTP endpoint is then available at http://127.0.0.1:1957/mcp. Stdio remains the recommended local-client transport. HTTP hosting, TLS, authentication, and proxy configuration are deployment concerns and are intentionally not prescribed by this project yet. Run quality checks with:

uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest

Ingestion

Maintainers can inspect the reviewed registry and run the complete source-to-index pipeline with:

uv run fortran-mcp source list
uv run fortran-mcp source sync SOURCE_ID --data-dir data

See Adding or updating a documentation source for the provenance, licensing, selection, and benchmark gate. The lower-level commands below remain useful when working on converters individually.

Fetch an approved documentation source by its registry ID:

uv run fortran-mcp-ingest fpm-0.13.0-docs
uv run fortran-mcp-ingest stdlib-0.8.1-docs
uv run fortran-mcp-ingest cmake-4.4.0-fortran-docs
uv run fortran-mcp-ingest openmp-6.0.1-fortran-examples
uv run fortran-mcp-ingest gnu-make-4.4.1-build-reference
uv run fortran-mcp-ingest numpy-2.5.2-f2py-docs
uv run fortran-mcp-ingest fypp-3.2-manual
uv run fortran-mcp-ingest openmpi-5.0.10-fortran-reference
uv run fortran-mcp-ingest fortitude-0.9.2-reference
uv run fortran-mcp-ingest codee-open-catalog-fortran-subset
uv run fortran-mcp-ingest old-fortran-programming-idioms
uv run fortran-mcp-ingest prima-modernization-case-study
uv run fortran-mcp-ingest beliavsky-fortran-packages-list
uv run fortran-mcp-ingest fortran-lang-package-index-additions

The core collection also includes separately identifiable Fortran-lang references for intrinsic procedures, the quickstart, best practices, object-oriented programming, Fortran 95, building and linking, Python-to-Fortran translation, and floating-point comparisons. They are pinned to one reviewed upstream revision and remain independently filterable in search results.

The OpenMP source contains the official 6.0.1 explanatory examples that have corresponding Fortran code. Its reviewed converter retains shared and Fortran-specific explanations, embeds the fixed- and free-form source examples, and excludes C/C++ listings. It is practical guidance rather than the normative OpenMP specification.

The GNU Make source is a deliberately small set of official 4.4.1 manual sections covering rules, prerequisites, automatic variables, parallel and recursive builds, diagnostics, and the built-in Fortran compiler variables and rules. Its modified-title and attribution notice, required cover texts, and complete GFDL are retained.

The Fypp source is the complete compact official 3.2 manual. It adds the preprocessor language, command-line definitions and includes, macro scopes, line markers, and Fortran-specific folding pitfalls that are not covered by the existing fpm configuration or F2PY generic-interface example. The pinned RST is converted to citation-ready Markdown without changing its substantive content.

The Fortitude source adds practical diagnostics for correctness, modernization, obsolete features, portability, and style. It uses Fortitude's pinned native Markdown: one page per rule plus the small set of pages needed to install, run, and configure the linter. Parser sources, tests, media, editor setup, integrations, and release history are excluded. The material complements language and compiler references; it is not treated as normative Fortran guidance.

The Codee Open Catalog source is limited to five independently useful pages that fill measured gaps: loop-invariant conditionals, three initialization hazards, and array-bounds errors. Its converter retains shared guidance and Fortran examples, removes C/C++ examples, rewrites internal links to the pinned revision, and adds the Apache-required modification notice. The rest of the catalog is excluded because it substantially overlaps existing sources or did not justify its retrieval weight. This is community guidance, not normative material or a product endorsement.

The legacy-migration material has two complementary roles. Old programming idioms explained converts nine MIT-licensed chapters about the meaning, hazards, and modern alternatives of old Fortran constructs. Its bibliography supplies external citation links but is not itself indexed; the unfinished outline, separate examples, PDF, and a redundant BLOCK DATA section that ranked below Fortitude's guidance are excluded. The much smaller PRIMA case-study subset contributes an official numerical-software workflow: establish a faithful reference, convert layout first, and test after every tiny refactoring. Neither source is treated as a language standard.

Ecosystem discovery uses two small, complementary directories. Beliavsky's actively curated list is the primary source and retains all 396 categorized fpm-compatible projects. The Fortran-lang package index adds 204 repositories absent from that snapshot; its 68 normalized-URL overlaps are removed deterministically. These entries help users find existing libraries and tools, but inclusion is not an endorsement or a guarantee of maintenance, licensing, compatibility, or a current successful build. Always check the linked project before adoption.

The GNU Fortran manual is generated from its pinned Texinfo sources. Maintainers building that source need GNU Texinfo 7.3 and the optional conversion dependency:

uv sync --extra ingest
uv run fortran-mcp-ingest gfortran-16.2.0-manual
uv run fortran-mcp-build gfortran-16.2.0-manual

On macOS, install Texinfo with brew install texinfo and add its bin directory to PATH as instructed by Homebrew. Texinfo is build-time maintainer tooling; users of prebuilt data bundles do not need it.

The command writes immutable source files and a checksum record below the configured per-user data directory. It refuses to overwrite an existing ingestion.

Set FORTRAN_MCP_DATA_DIR to keep generated documents and indexes elsewhere, such as the repository data/ directory during maintainer work or a larger disk. All data commands and the server use that location.

Build citation-preserving document chunks after ingestion:

uv run fortran-mcp-build fpm-0.13.0-docs
uv run fortran-mcp-build stdlib-0.8.1-docs
uv run fortran-mcp-build cmake-4.4.0-fortran-docs
uv run fortran-mcp-build openmp-6.0.1-fortran-examples
uv run fortran-mcp-build gnu-make-4.4.1-build-reference
uv run fortran-mcp-build fortitude-0.9.2-reference
uv run fortran-mcp-build codee-open-catalog-fortran-subset
uv run fortran-mcp-build old-fortran-programming-idioms
uv run fortran-mcp-build prima-modernization-case-study
uv run fortran-mcp-build beliavsky-fortran-packages-list
uv run fortran-mcp-build fortran-lang-package-index-additions
uv run fortran-mcp-index

The MCP server exposes search_fortran_docs, which returns ranked passages with the source, version, authority, document type, topical facets, heading hierarchy, line range, and published documentation URL. Searches can be narrowed by source ID, document type, authority, topic, compiler, source version, or Fortran language version. For example, clients can combine compiler="gfortran" and version="16.2.0". A Fortran language-version filter is intended for edition-specific sources, rather than as a claim that a compiler completely implements an edition. Applicability filters are resolved before ranking for lexical, semantic, and hybrid retrieval.

It also exposes MCP resources for registered sources, source provenance, and exact chunks:

fortran-docs://sources
fortran-docs://sources/{source_id}
fortran-docs://chunks/{chunk_id}

Run the reviewed retrieval benchmark against the local index with:

uv run fortran-mcp-benchmark --output benchmarks/results/sqlite-fts5.json

The report records ranking accuracy, negative-query accuracy, latency, and every individual query result. It is a baseline for comparing future lexical, semantic, or hybrid search providers.

To measure whether each source earns its footprint, run the leave-one-source-out analysis:

uv run fortran-mcp-contributions --data-dir data \
  --output benchmarks/results/source-contributions.json

It records unique passes, regressions, vector and byte costs, and latency for the baseline and each omitted source. The concise reviewed result lives in benchmarks/results/source-contributions.md.

To build and evaluate the optional local semantic index:

uv sync --extra semantic
uv run fortran-mcp-semantic-index
uv run fortran-mcp-benchmark --provider semantic \
  --output benchmarks/results/semantic-bge-small-en-v1.5.json
uv run fortran-mcp-benchmark --provider hybrid \
  --output benchmarks/results/hybrid-bge-small-en-v1.5.json

The semantic-index command downloads the configured embedding model on its first run. Later builds reuse vectors whose model and embedded passage content are unchanged, embed only new or changed chunks, and discard removed chunks. Pass --rebuild to regenerate every vector. Chunks are embedded in length-sorted batches, which roughly halves indexing time on mixed-length corpora without changing any embedding. The generated index stays in the data directory and records both the model name and the lexical-index checksum, so a stale or incompatible index is rejected.

Lexical search remains the server default. After building the semantic index, select another local provider with FORTRAN_MCP_SEARCH_PROVIDER=semantic or FORTRAN_MCP_SEARCH_PROVIDER=hybrid.

Hybrid search conservatively returns no passages when its top semantic score is below the reviewed baseline threshold. An explicit source filter bypasses this automatic abstention because the caller has already stated which documentation applies. An explicit registered dialect name, such as OpenMP, can also establish applicability when lexical results from that dialect are present. The threshold is calibrated against both supported questions and uncovered, domain-adjacent questions, and must be reviewed whenever the core source collection or embedding model changes.

Data bundles

Normal users will consume prebuilt data bundles rather than run ingestion or indexing locally. The current tooling defines two roles: core contains the lexical index and required source license notices; semantic contains document vectors and declares the exact core-index checksum and query model it requires.

Build and verify local artifacts with:

FORTRAN_MCP_DATA_DIR=data uv run fortran-mcp-bundle build core \
  --output dist/fortran-mcp-core.zip
FORTRAN_MCP_DATA_DIR=data uv run fortran-mcp-bundle build semantic \
  --output dist/fortran-mcp-semantic.zip
uv run fortran-mcp-bundle verify dist/fortran-mcp-core.zip
uv run fortran-mcp-bundle install dist/fortran-mcp-core.zip
uv run fortran-mcp-catalog build --data-version 2026.08.1 \
  --output dist/catalog.json \
  dist/fortran-mcp-core.zip dist/fortran-mcp-semantic.zip
uv run fortran-mcp-catalog install core --catalog dist/catalog.json

Publishing a data release

1. Rebuild both bundles deterministically from a current data directory and regenerate the catalog (commands above). Bundle versions default to the package version; pick a new YYYY.MM.N data_version for each data release.
2. Verify every artifact on its own and through the catalog:

   uv run fortran-mcp-bundle verify dist/fortran-mcp-core.zip
   uv run fortran-mcp-bundle verify dist/fortran-mcp-semantic.zip
   uv run fortran-mcp-catalog verify dist/catalog.json
   

3. Smoke-test the exact artifacts before upload:

   rm -rf /tmp/release-check
   FORTRAN_MCP_DATA_DIR=/tmp/release-check uv run fortran-mcp data install core \
     --catalog dist/catalog.json
   FORTRAN_MCP_DATA_DIR=/tmp/release-check uv run fortran-mcp data install semantic \
     --catalog dist/catalog.json
   FORTRAN_MCP_DATA_DIR=/tmp/release-check uv run fortran-mcp data verify
   

4. Upload all assets together to a draft release so the catalog never points at missing files:

   gh release create v<version> --draft --title "Fortran MCP <version> data release" \
     dist/catalog.json dist/fortran-mcp-core.zip dist/fortran-mcp-semantic.zip
   

5. Inspect the draft (gh release view v<version>): exactly three assets, correct sizes, no stray uploads. Publishing is the activation step because releases/latest/download/catalog.json resolves to this release immediately.
6. Publish only after every asset is present:

   gh release edit v<version> --draft=false
   

7. Post-publish, exercise the real user path without --catalog: fortran-mcp data install core && fortran-mcp data verify. Release assets are only downloadable anonymously from a public repository, so this final check requires the repository to be public.

There is no automated rollback: fix the artifacts and cut a new data release instead. Old installs remain valid because verification is checksum-pinned.

Normal users use the built-in GitHub Release catalog through the unified command:

fortran-mcp data install core
fortran-mcp data verify
fortran-mcp data remove core

Running fortran-mcp without a subcommand still starts the stdio MCP server, so existing client configuration remains compatible. fortran-mcp doctor lists installed data, including custom corpora built with source sync; fortran-mcp doctor --json is machine-readable. data remove removes exactly one named data package after confirmation, keeps unrelated files in the data directory, and removes documentation data only — not the Python package itself. If installed with uv tool, uninstall that separately with uv tool uninstall fortran-mcp.

Bundles use a versioned manifest, deterministic ZIP metadata, stable file ordering, and SHA-256 checksums for every payload. The default catalog is loaded over HTTPS from the latest GitHub Release; --catalog accepts another HTTPS URL or local path. Relative artifact paths are resolved against the catalog URL, and the advertised archive size and SHA-256 are checked before the bundle's own manifest and payload checks. Installation enforces server compatibility and installs semantic data only alongside the exact required core index. See Data bundle format for the artifact contract.

See Connect an MCP client for Codex, Claude Desktop, and generic stdio configuration examples.

See Contributing for local checks and source-submission expectations. Coding agents should also read AGENTS.md for the repository map and invariants.

Source policy

The 23-source core is intentionally frozen for the first release. A new source is considered only when realistic benchmark questions demonstrate a gap, the exact material has clear transformation and redistribution rights, and a trial shows enough unique retrieval value to justify its bytes and ranking interference. Public access alone is not permission to redistribute documentation; this is especially relevant to standards, books, and vendor manuals.

The reviewed source inventory lives in docs/sources.toml; its policy is described in docs/README.md.

License

The server software is available under the MIT License. Ingested documentation retains its original copyright and license.