Skip to content

Docs: align CLI, deployment, fastmcp.json, and contributor workflow behavior #4256

@strawgate

Description

@strawgate

Several CLI/deployment/config/contributor docs describe old behavior, which makes copy-pasted examples fail or teach the wrong defaults.

Concrete drift found in the docs audit:

  • fastmcp call can call tools, read resource URIs, and render prompts with --prompt, but the CLI docs only describe tool calls.
  • Install docs use stale flags like --server-name, -e, and -f; current install commands expose --name/-n, --with-editable, and --env-file.
  • HTTP deployment/config docs mention stale defaults such as port 3000 and /mcp/; runtime defaults are port 8000, Streamable HTTP path /mcp, and SSE path /sse.
  • Config docs imply broad config-file auto-detection; the implementation only auto-detects a file named exactly fastmcp.json when no path is supplied.
  • streamable-http is accepted as a config alias and normalized to http, which should be documented consistently.
  • Contributor workflow docs still show uv run pytest where the repo guidance expects uv run pytest -n auto, and the contrib guide should reflect the issue-first workflow for in-repo contrib modules.

Expected: the CLI, deployment, config, and contributor workflow docs should match current command flags, runtime defaults, config-file loading behavior, and repo contribution guidance.

Verified against current code, repo guidance, and tests:

  • AGENTS.md / CLAUDE.md
  • CONTRIBUTING.md
  • fastmcp_slim/fastmcp/cli/client.py
  • fastmcp_slim/fastmcp/cli/install/*
  • fastmcp_slim/fastmcp/settings.py
  • fastmcp_slim/fastmcp/server/mixins/transport.py
  • fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py
  • tests/cli/*

A focused local validation pass for the candidate docs updates passed: docs examples, broken links, prek, and CLI tests.

Metadata

Metadata

Assignees

Labels

cliRelated to FastMCP CLI commands (run, dev, install) or CLI functionality.documentationUpdates to docs, examples, or guides. Primary change is documentation-related.fastmcp.jsonFunctionality related to fastmcp.json or FastMCPConfig files.httpRelated to HTTP transport, networking, or web server functionality.

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