mcp-simple-job

하위 작업을 다른 머신의 로컬 모델에 넘기고, 결과를 반환하기 전에 검증하세요.

특정 형태의 문제를 위해 만들어졌습니다. 성능이 좋고 요금이 측정되는 어시스턴트는 여러분이 앉아 있는 머신에서 실행되는 반면, 충분히 쓸 만한 GPU 박스는 구석에서 놀고 있습니다. 파일 40개를 읽기, 긴 페이지 요약하기, 데이터셋 내려받기 — 이런 작업 중 어느 것도 비싼 모델이 필요하지 않으며, 어시스턴트의 컨텍스트에서 처리하면 진짜로 부족한 유일한 리소스를 소모합니다.

저자의 환경에서 동일한 작업 네 가지를 컨텍스트 안에서 처리하는 것과 비교해 측정한 결과: 약 2.7배 빠르고, 컨텍스트 소모는 6.1배 적습니다. 원본 페이지가 컨텍스트에 들어오지 않기 때문입니다.

단 하나의 규칙

작업에는 반드시 검증(check)이 따라야 합니다. 어떻게 성공했는지 알 수 있는 방법을 명시할 수 없는 작업은 거부됩니다 — 경고가 아니라 거부입니다.

이것은 로컬 모델에 대한 불신이 아닙니다. 호출자가 알 수 없기 때문입니다. 어시스턴트가 요약을 위임하고 400단어의 자신 있는 문장을 돌려받았을 때, 그 문장이 문서를 설명하는지 다른 무언가를 설명하는지 독립적으로 알 방법이 없습니다. 검증 없이 위임하면 초록불이 아무 의미도 없는 지점이 하나 더 생깁니다.

검증은 의도적으로 단순합니다: nonempty, contains, regex, json_keys, line_count, shell(여러분의 argv, 종료 코드 0이면 통과, 출력은 stdin으로 전달), summary_of(원본보다 짧고 원본을 복사한 것이 아님).

Related MCP server: any-model-plugin

네 가지 하위 작업

simple_job_stats는 모든 작업마다 기록되는 원장(ledger) 행을 바탕으로 그것들이 실제로 어떻게 진행되었는지 보고합니다.

실행하기

요구 사항

• MCP 서버를 실행하는 머신에 Node 18+.

• OpenAI 호환 채팅 엔드포인트. llama.cpp의 llama-server, Ollama, vLLM, LM Studio, 또는 호스팅 API — POST /v1/chat/completions에 응답하는 모든 것.

• 가져오기(fetch)를 수행하는 머신에 Python 3.9+. 표준 라이브러리만 사용합니다. pip 설치도, node도, beautifulsoup도 없습니다.

• 두 번째 머신에 SSH 키 인증, 사용하는 경우에 한합니다. 선택 사항입니다(아래 참조).

저자 머신에서의 연결 구성

두 대의 컴퓨터:

• Mac mini — 일상 업무용 워크스테이션. 16GB, 보통 몇 GB는 스왑에 들어갑니다. Claude Desktop을 실행하며 따라서 이 MCP 서버도 실행합니다.

• RTX 5070 Ti가 장착된 Pop!_OS 박스 — 실험실. 포트 8080에서 llama-server 아래 ornith라는 35B 모델을 실행하며, 하루 대부분은 유휴 상태입니다.

SSH 터널 덕분에 원격 모델이 Mac에서는 로컬처럼 보입니다:

ssh -N -o ServerAliveInterval=30 -L 127.0.0.1:8081:127.0.0.1:8080 pop-os

pop-os는 키와 IdentitiesOnly yes가 있는 ~/.ssh/config 별칭이라, 서버가 BatchMode=yes로 비대화식으로 도달할 수 있습니다.

MCP 클라이언트 항목은 그냥 이렇게:

{ "mcpServers": { "simple-job": { "command": "node", "args": ["/path/to/mcp-simple-job/index.js"] } } }

기본값이 나머지를 처리합니다: 127.0.0.1:8081의 모델, pop-os의 워커 머신, 그리고 기존의 ~/Code/harness/가 있으면 거기의 원장.

그 어떤 것도 손으로 호출되지 않습니다. 어시스턴트가 도구를 선택합니다 — 이것은 생각보다 어려운 문제이며, 아래에서 다룹니다.

여러분 환경에서 실행하기

두 대의 머신, 하나는 클라이언트, 하나는 모델 실행:

{
  "mcpServers": {
    "simple-job": {
      "command": "node",
      "args": ["/path/to/mcp-simple-job/index.js"],
      "env": {
        "ORNITH_URL": "http://127.0.0.1:8081/v1/chat/completions",
        "ORNITH_MODEL": "your-model-name",
        "POP_HOST": "your-ssh-alias"
      }
    }
  }
}

한 대의 머신 — 전부 로컬, SSH 없음:

{
  "env": {
    "ORNITH_URL": "http://127.0.0.1:11434/v1/chat/completions",
    "ORNITH_MODEL": "qwen3:8b",
    "SEARCH_HOSTS": "mac"
  }
}

SEARCH_HOSTS=mac는 "두 번째 머신이 없다"는 뜻의 스위치입니다. 가져오기, 다운로드, 검색이 모두 로컬에서 일어나며, 검색은 단순히 예산(rate budget)이 두 개 대신 하나입니다. 나머지는 동일하게 동작합니다.

환경 변수

원장은 선택 사항입니다. 처음 사용할 때 생성되며, 쓸 수 없어도 작업은 계속 실행됩니다 — 로깅은 best-effort이고 작업을 절대 막지 않습니다. HARNESS_TRACE는 저자 자신의 추적 설정을 위한 훅입니다. 무시하면 행에 trace id가 null로 찍힐 뿐입니다.

실제로 사용되게 만들기

대부분의 사람들이 건너뛰는 부분이고, 위의 모든 것이 의미 있는지 결정하는 부분입니다.

아무도 라우팅하지 않는 도구는 아무리 잘 작동해도 보이지 않습니다. 저자에게는 완벽하게 작동하는 별도의 MCP 서버가 있는데 몇 달 동안 호출이 0건이었습니다. 순전히 어시스턴트에게 그 도구를 사용하라고 말한 적이 없었기 때문입니다. 능력을 만드는 것과 그 능력으로 라우팅하는 것은 서로 다른 두 가지 작업이며, 첫 번째를 끝내면 끝난 것처럼 느껴집니다.

그 간격을 줄이는 세 가지 방법, 가장 저렴한 것부터. 대부분의 사람들은 두 번째를 원합니다.

1. 아무것도 하지 말고 지켜보기. 일부 클라이언트는 도구 설명을 충분히 잘 읽어서 충분히 명확한 요청 — "이 페이지 40개를 요약해 줘" — 이 스스로 도구를 찾아냅니다. 기계 장치를 추가하기 전에 하루 정도 시도해 볼 가치가 있습니다. 실제로 호출되는지 지켜보세요.

2. 클라이언트가 상시 지침을 두는 곳에 규칙을 넣기. Claude Desktop 프로젝트 지침, Claude Code용 CLAUDE.md, .cursorrules, 커스텀 GPT의 지침 — 클라이언트가 매 턴 읽는 무엇이든 좋습니다. 예를 들면:

simple-job을 통해 사용할 수 있는 로컬 모델이 있습니다. 자료가 아직 컨텍스트에 없고 작업이 기계적일 때 사용하세요: 페이지나 파일 요약, 웹 검색 후 읽기, 다운로드 가져오기, 추출 및 재포맷. 무료이고 원본에 컨텍스트를 소모하지 않습니다.

텍스트가 이미 컨텍스트에 있을 때, 작업이 해석보다는 필사(transcription)가 아니라 해석을 요구할 때, 또는 '맞는 것'보다 '검증 가능한 것'이 더 중요할 때는 직접 하세요. 판단이 필요한 호출, 반드시 정확해야 하는 코드, 파일 편집은 절대 위임하지 마세요.

모든 작업에는 검증이 따라야 합니다 — 서버는 검증할 수 없는 작업을 거부합니다.

위임하지 말아야 할 때에 대해 위임해야 할 때만큼 많은 말을 쓰세요. 위임 도구의 라우팅에서 나타나는 실패 모드는 과도한 위임이며, 모든 것을 아래로 내려보내는 어시스턴트는 여러분이 판단을 원했던 자리에 충실한 필사를 건넬 것입니다.

3. 라우터가 있다면 그에 연결하기. 이미 상황을 도구에 매칭하는 설정이 있다면 "아직 컨텍스트에 없는 자료의 대량 읽기 또는 가져오기" 항목을 추가하세요. 상시 지침보다 유리한 점은 측정 가능하다는 것입니다 — 제때 발동했는지 셀 수 있습니다. 상시 지침은 작동하거나 작동하지 않을 뿐이고, 어느 쪽인지 기록하는 것은 없습니다.

보내지 말아야 할 것

"그럴듯해 보인다"가 유일한 테스트인 모든 것. 판단이 필요한 호출. 반드시 정확해야 하는 코드. 파일 편집.

그리고 취향이 아니라 측정으로 발견된 경계 하나: 작은 로컬 모델은 충실하게 필사하지만 해석하지는 않습니다. 테스트에서 원본의 모호한 표현을 무엇을 의미하는지 해결하는 대신 그대로 재현했고, 저장소의 스타 수를 버그 리포트의 일부인 것처럼 요약했습니다. 필사는 보내세요. 해석은 직접 하세요.

만들면서 얻은 기록

아래는 모두 의견이 아니라 측정 결과입니다. 숫자는 코드 주석에도 있습니다.

생각(thinking)은 기본적으로 꺼져 있음

추론 모델은 자신의 숙고와 답을 같은 토큰 예산에서 내보냅니다. 동일한 요약 작업을 세 번 동일하게 실행했을 때, 세 번 중 두 번은 5,500~6,000자를 생각하는 데 쓰고 한도에 도달한 다음 HTTP 200과 함께 빈 답변을 반환했습니다.

max_tokens를 올려도 고쳐지지 않았습니다. reasoning_effort: "low"도 고쳐지지 않았습니다. /no_think 시스템 태그도 고쳐지지 않았습니다. 오직 chat_template_kwargs: {enable_thinking: false}만 효과가 있었고, 같은 작업이 그다음 258토큰으로 답했습니다. 진짜 숙고가 필요한 작업에는 think: true를 넘기고, 그와 함께 max_tokens도 올리세요.

검색은 배급되며, DuckDuckGo는 그 이유를 속임

DuckDuckGo는 정중하게 속도 제한을 하지 않습니다:

• 서비스된 쿼리는 HTTP 200, 약 28KB, 결과 링크 10개

• 거부된 쿼리는 HTTP 202, 약 14.2KB, 본문은 "Please complete the following challenge... Select all squares containing a duck" 라고 읽힙니다

IP에 대한 캡차 플래그이지 시간 제한이 아니며, 간격을 두는 것으로는 해제되지 않습니다. 4분간 조용히 있다가 한 머신에서 30초 간격으로 6개 쿼리, 다른 머신에서 15초 간격으로 6개 쿼리를 보냈더니 12개 모두 실패했습니다. 블록 동안 5초마다 폴링해도 162초 안에 회복되지 않았습니다 — 재시도가 오히려 키웁니다. 플래그는 약 20분 만에 스스로 사라졌습니다.

그래서 검색은 간격을 두고, 머신을 번갈아 가며(IP 두 개는 예산 두 개), 속도 제한은 throttled로 보고되며 결코 "결과 없음"으로 보고되지 않습니다. 그 둘은 반대 의미입니다.

읽기는 질문을 따라감

긴 페이지는 모델의 창에 맞게 잘리는데, 위에서부터 자르면 조용히 잘못된 질문에 답하게 됩니다. 40,063자 페이지에서 8,000자 창으로 "sparse gating and load balancing" 을 물었을 때, 첫 번째 버전은 기사 서두의 유창한 요약을 반환했습니다 — 그 서두에는 "load balancing"이 전혀 등장하지 않는데(16,181자에서 시작), "sparse"도 등장하지 않습니다(14,671자).

그래서 focus가 창을 조정합니다: 맥락을 위한 머리부분, 그 다음 각 명명된 용어 주변의 구절들, 어떤 용어가 두 번째 창을 받기 전에 각 용어당 하나의 창이 보장됩니다. 이전 두 버전으로는 충분하지 않았습니다 — 부분 문자열 매칭이 "download" 안에서 "load"를 찾아 노이즈 42건을 보고했고, 문서 순서대로 구절을 가져가면 16,181자에 도달하기 전에 예산을 다 써버렸습니다.

페이지가 그 단어들을 전혀 사용하지 않으면, 호출은 focus_not_found와 함께 ok:false를 반환합니다. 0건의 적중은 다른 자료의 그럴듯한 요약보다 더 나은 답변입니다.

대부분 스크립트인 페이지는 거부됨

어떤 사이트는 68,896바이트를 제공했는데 그중 텍스트는 40자("Loading...")뿐이었고, 원래의 if not text 가드가 통과시켰습니다 — 그래서 셸이 소스 자료로 요약에 들어갔고, 모델은 그것을 인용하며 자신 있는 벤치마크 수치를 써냈습니다.

이제 두 가지 테스트를 사용합니다. 각각 단독으로는 속기 때문입니다. 절대 하한선과, 또한 짧은 페이지만을 거부하는 텍스트-바이트 비율입니다. GitHub 이슈는 실제 토론 3,896자 주위에 290,000바이트의 마크업이 있으며, 비율만으로는 이를 버렸습니다.

인용은 확인할 수 있도록 번호가 매겨집니다

search_and_summarize는 페이지에 번호를 매기고 url 대신 [1], [2]를 요청합니다. url을 요청했을 때, 모델은 블로그에서 읽은 수치를 문서 페이지에 귀속시켰습니다. 사실은 실제이고 자료에 있었지만, 귀속은 그렇지 않았습니다. 그리고 summary_of는 이를 볼 수 없습니다. 잘못 라벨링된 불릿은 올바른 길이이고 복사본이 아니기 때문입니다.

url은 올바르게 복사하기에는 길고 불투명한 문자열입니다. 정수는 그렇지 않으며, 실제로 읽은 페이지에 대해 범위 검사를 할 수 있습니다. 코드는 이를 수행하여 범위를 벗어난 숫자에 대해 호출을 실패시키고 출처가 전혀 없는 불릿을 집계합니다.

어느 머신이 더 빠른가?

양쪽에서 동일한 sha256으로 검증됨:

클라이언트 머신이 둘 다에서 더 빨랐습니다. 속도는 워커에게 작업을 보내는 이유가 아닙니다. 이유는 워커가 모델을 보유하고 있고, 다른 머신이 사용 중일 때 유휴 상태이며, 두 번째 머신이 두 번째 검색 예산이기 때문입니다. 다운로드 호스트는 처리량이 아니라 파일이 필요한 위치에 따라 선택하세요.

테스트

node test_e2e.mjs                        # 24 assertions, spawns the real server over JSON-RPC
node --test test/simple-job.test.mjs     # 19 unit assertions on the checks

엔드투엔드 스위트는 일회용 원장을 대상으로 클라이언트가 하는 방식대로 실제 서버를 생성합니다. 인프로세스 테스트는 PATH 또는 환경 버그를 잡지 못하며, 이러한 버그는 정확히 재시작 후에만 나타나는 종류입니다.

index.js에 대한 변경 사항은 클라이언트가 다음에 서버를 시작할 때 적용됩니다. pop_agent.py는 모든 호출에서 다시 읽히므로 가져오기, 검색 및 다운로드에 대한 변경 사항이 즉시 적용됩니다.