Question 1

/tools/{name}/disable?version=v1을 호출한 후 FastMCP tools/list에서 발생하는 "'str' object has no attribute 'matches'" 오류를 어떻게 수정하나요?

Accepted Answer

이 문제는 component-manager 라우트가 원시 `?version=` 쿼리 문자열을 `VersionSpec` 객체를 기대하는 `Provider.enable/disable`에 그대로 전달하기 때문에 발생합니다. 이 잘못된 문자열은 이후 visibility transform에서 사용되어, 그 이후의 모든 `tools/list` 호출이 실패하게 됩니다.

임시 해결 방법:
1. 쿼리 파라미터 없이 라우트를 호출하세요:
   ```bash
   curl -X POST http://localhost:8000/tools/mytool/disable
   ```
2. 잘못된 상태가 이미 저장된 경우, FastMCP 서버를 재시작하거나 다시 생성하세요.
3. 특정 버전을 대상으로 해야 한다면, HTTP 라우트를 사용하는 대신 `VersionSpec`을 사용하여 provider API를 직접 호출하세요.

영구적인 해결책: component-manager 수정이 포함된 FastMCP 릴리스로 업그레이드하거나, 파라미터를 provider에 전달하기 전에 변환하도록 라우트 핸들러를 패치하세요:
   ```python
   raw_version = request.query_params.get("version")
   version = VersionSpec(eq=raw_version) if raw_version else None
   await provider.disable(name=name, version=version)
   ```
해당하는 enable 라우트에도 동일한 변환을 적용하세요. 이 문제는 FastMCP `4.0.11.dev1+0ebabc0c`에서 재현되었습니다.

Question 2

client_capabilities.extensions에 해당 확장이 포함되어 있음에도 FastMCP의 client_supports_extension이 False를 반환하는 이유는 무엇인가요?

Accepted Answer

이 문제는 fastmcp 4.0.5와 mcp 2.2.0 및 프로토콜 버전 2026-07-28에 영향을 줍니다. `client_supports_extension()`은 `session.client_params`가 `None`이면 조기에 반환하지만, 요청별 envelope에서 `clientInfo`는 선택 사항이므로 `session.client_capabilities.extensions`가 채워져 있어도 `client_params`가 없을 수 있습니다. 해결 방법으로, `client_supports_extension()`을 호출하는 대신 capabilities를 직접 검사하세요:

```python
from fastmcp.server.dependencies import get_context

ctx = get_context()
caps = ctx.session.client_capabilities
supported = bool(
    caps is not None
    and caps.extensions is not None
    and "io.modelcontextprotocol/ui" in caps.extensions
)
```

영구적인 수정 방법은 `client_supports_extension()`이 `session.client_params`의 존재를 요구하는 대신 `session.client_capabilities`를 사용하도록 하는 것입니다. 해당 수정이 릴리스되면 FastMCP를 업그레이드하세요.

Question 3

FastMCP task-enabled 도구가 인수가 누락되었거나 알 수 없는 경우 validation error 대신 일반적인 "Error calling tool"을 반환하는 이유는 무엇인가요?

Accepted Answer

이 문제는 FastMCP 4.0.12.dev에서 발생합니다. 작업 제출 시 인자 타입은 검증했지만 작업을 큐에 추가하기 전에 전체 호출 형태는 검증하지 않았기 때문입니다. 필수 인자 누락이나 예상치 못한 인자는 워커가 함수를 실행할 때만 감지되었으며, 특히 `mask_error_details=True`인 경우 불투명한 작업 오류를 발생시켰습니다.

"Reject missing and unexpected arguments at task submission"(작업 제출 시 누락된 인자 및 예상치 못한 인자 거부) 수정이 포함된 FastMCP 릴리스로 업그레이드하세요:

```bash
pip install -U fastmcp fastmcp-tasks
```

업그레이드 후에는 작업 지원 도구가 제출 시점에 인자를 검증하고, `Missing required argument` 또는 예상치 못한 인자 오류와 같이 동기 도구와 동일한 Pydantic 검증 오류를 반환합니다.

임시 진단 우회 방법으로, `mask_error_details=False`로 설정하거나 작업 지원 도구를 호출하기 전에 도구의 스키마에 대해 페이로드를 검증하세요.

Question 4

SKILL.md 파일이 유효한 UTF-8이 아닐 때 SkillsDirectoryProvider UnicodeDecodeError를 어떻게 수정하나요?

Accepted Answer

FastMCP 4.0.11.dev에서 잘못된 UTF-8 `SKILL.md` 파일 하나가 `SkillsDirectoryProvider`의 모든 스킬 로딩을 막을 수 있습니다. 문제가 되는 파일을 UTF-8로 변환하거나 스킬 디렉터리에서 제거하세요. UTF-16 파일의 경우 다음을 실행하세요: `iconv -f UTF-16 -t UTF-8 bad/SKILL.md -o bad/SKILL.md.utf8 && mv bad/SKILL.md.utf8 bad/SKILL.md`. Python에서는 `Path.read_text(encoding="utf-16").encode("utf-8")`를 사용하여 파일을 감지하고 다시 작성할 수 있습니다. 변환 후 provider를 재시작하면 유효한 스킬이 정상적으로 로드됩니다.

Question 5

FastMCP에서 매개변수가 없는 도구의 설명에 Returns 섹션이 포함되는 이유는 무엇인가요?

Accepted Answer

이것은 FastMCP 3.4.7의 docstring 파싱 버그입니다. `parse_docstring()`은 파서가 추출한 설명을 `parameters` 섹션도 함께 찾은 경우에만 사용합니다. 매개변수가 없는 도구의 경우 파싱이 원본 docstring으로 폴백되므로, `Returns:`, `Yields:`, `Raises:` 섹션이 클라이언트에 표시되는 설명에 유출됩니다. 이 수정은 매개변수를 찾지 못하더라도 추출된 최적의 설명을 유지하도록 파서를 업데이트합니다. issue #4952에 대한 수정이 포함된 FastMCP 릴리스로 업그레이드하세요. 해결 방법으로 설명을 명시적으로 설정할 수 있습니다:

```python
@mcp.tool(description="Return current status.")
async def status() -> dict[str, bool]:
    """Return current status.

Returns:
        A dict containing the current status.
    """
    return {"ok": True}
```

또는 업그레이드할 때까지 도구 docstring에서 `Returns:`/`Yields:`/`Raises:` 섹션을 제거하세요.

fastmcp

개요

README 미리보기

FAQ (5)

同类型项目

tensorflow

superpowers

everything-claude-code

flutter