MCP 도구 설명을 위한 linter를 오픈 소스화했습니다

AI 에이전트는 이름, 설명, 입력 스키마 세 가지를 읽고 MCP(Model Context Protocol) 도구를 선택합니다. 많은 서버들은 이미 파일의 내용을 아는 인간을 위해 docstring처럼 이러한 설명을 작성합니다. 하지만 컨텍스트에 30개의 도구가 있는 에이전트는 그렇지 못합니다. 이 에이전트는 언제 어떤 도구를 사용해야 하는지, 무엇이 반환되는지, 그리고 대신 어떤 유사한 도구를 사용해야 하는지를 알아야 합니다.

Forecall의 linter가 바로 이를 확인하며, 해당 코드는 Apache-2.0 하에 공개되었습니다: github.com/forecall/forecall-cli.

실제 서버에서 사용해 보기

두 개의 명령어만 필요합니다. 첫 번째는 서버를 시작하고 도구 목록을 저장하며, 두 번째는 이를 점수화합니다.

npx forecall dump -o memory.json -- npx -y @modelcontextprotocol/server-memory
npx forecall lint memory.json

공식 메모리 서버(0.6.3)에 대한 보고서의 일부는 다음과 같습니다:

Average score     43.8 / 100
Tools             9
Confusable pairs  1
...

설명이 유사한 두 개의 도구가 삭제되었는데, 둘 다 언제 사용해야 하는지에 대한 언급이 없습니다. 이는 에이전트가 잘못된 것을 삭제할 수 있는 종류의 쌍입니다. 저는 servers 리포지토리의 이슈에서 이들에 대한 재작성을 제안했습니다.

원격 서버의 경우, URL을 전달하고 키가 필요한 경우 `--header

Nothing leaves your machine

lint는 오프라인에서 작동합니다. 점수 계산은 의존성이나 네트워크 코드가 없는 패키지인 @forecall/lint에 있습니다. dump만 네트워크와 통신하며, 지정된 서버에만 연결됩니다. 이 명령어가 작성하는 JSON은 도구가 어디서 왔는지 기록할 뿐, 헤더나 환경 값은 절대 기록하지 않습니다.

알려줄 수 없는 것들

점수는 텍스트와 스키마를 읽는 규칙에서 나옵니다. browser_close 같은 짧은 설명이라도 모든 모델이 이를 올바르게 사용한다고 해도 점수가 낮게 나올 수 있으며, 높은 점수가 곧 모델이 올바른 도구를 선택할 것이라는 것을 증명하지는 않습니다. 이 점수는 어디에 더 많은 설명을 작성해야 하는지 찾는 데 사용하세요. (Forecall의 호스팅 평가(Evaluations)에서는 실제 모델을 사용하여 귀하의 도구들을 테스트합니다. 유료이며, 이 저장소에는 포함되어 있지 않습니다.)

이를 통해 발견한 것들

저희는 Smithery에서 가장 많이 사용되는 46개 서버에 대해 이 기능을 실행했습니다: 총 1,118개의 도구 중 769개(69%)가 언제 사용해야 하는지 명시하지 않았습니다. 전체 내용은 여기에서 확인하실 수 있습니다.

피드백 환영

규칙은 v1이며, 저는 어떤 부분이 잘못되었는지 듣고 싶습니다. 해당 글을 읽은 독자가 이미 하나의 제안을 했습니다: 두 도구가 유사한 것으로 표시될 경우, 각 설명에 서로를 언급해야 합니다. 이는 현재 issue #7에서 다루고 있습니다. 이슈와 풀 리퀘스트는 환영합니다.

저는 Forecall의 제작자입니다.