EXPERIMENTAL · MCP SERVER

SF:// MCP

SF:// 뉴스레터를 AI 에이전트가 직접 읽고 검색·인용할 수 있게 하는 출판 통로. Claude Desktop·Cursor·Codex 등 모든 MCP 호환 클라이언트에서 한 블록 설정으로 동작합니다.

English version: SF:// MCP — Read SF:// from your AI agent →

01 · MCP가 뭔가요?

AI 비서가 외부 도구를 부르는 표준 형식 — USB 같은 약속입니다.

MCP(Model Context Protocol)는 Anthropic이 2024년 11월에 발표한 오픈 표준입니다. 한 줄로 말하면 — AI 비서가 어떤 외부 데이터·도구든 같은 모양의 플러그로 부를 수 있게 한 약속입니다.

예전엔 AI가 외부 데이터를 가져오려면, 사이트마다 다른 API를 일일이 익히거나, 사람이 페이지를 열어 복사·붙여넣기를 해줘야 했습니다. MCP가 깔리면 — AI 비서는 마치 USB 케이블을 꽂듯 이 표준 인터페이스 한 가지만 알면 됩니다. 어떤 출판물이든, 어떤 데이터베이스든, 같은 방식으로.

발표 이후 18개월 만에 SDK 월간 다운로드가 10만 → 9700만으로 970배 늘었고, Adobe Marketo·Klaviyo·Brevo 같은 회사가 자사 운영 도구를 MCP로 노출했습니다. 그러나 출판물 본인이 자기 자신을 MCP로 내어주는 사례는 아직 거의 없습니다.

02 · 왜 신문이 MCP를 열어야 하나요?

독자 한 명 한 명에게 자기 AI 비서가 생기고 있기 때문입니다.

의사에겐 진료 가이드를 정리하는 비서, 변호사에겐 판례를 추적하는 비서, 회계사에겐 세무 안내서를 따라 읽는 비서. 그 비서들은 매일 수십 개의 출처를 들춥니다. 출판물이 비서가 부를 수 있는 도구로 자기 자신을 내어주면, 인용·요약·검색의 디폴트 경로가 출판물 본인의 통제 아래로 들어옵니다.

그렇지 않으면 — 외부 스크래퍼가 그 자리를 차지합니다. 출판물 본인이 어디에서 어떻게 읽혔는지 모른 채, 정작 내용은 다른 도구를 거쳐 AI 비서에게 흘러갑니다. 글로벌 대형 publisher 대부분이 지금 그 상태에 있습니다.

SF://는 가장 작은 publisher가 가진 비대칭 — 무료·CC BY-NC·1인 에디터 — 으로, 이 출판 양식을 먼저 시도합니다. 관련 칼럼: 「에이전트가 직접 읽는 신문 — frontier는 작은 publisher 손에 먼저 열렸다」

03 · 무엇이 가능해지나요?

AI 비서에게 SF://를 직접 묻는 다섯 가지 도구.

list_issues

"SF:// 최근 호 목록 보여줘" → AI가 발행된 모든 호의 제목·발행일·요약을 받아옵니다. 어느 호가 있는지 한 번에 보고 고를 수 있습니다.

get_issue

"5월 4일 호 핵심만 알려줘" → AI가 그 호의 풀 본문을 받아 정확한 인용으로 답합니다. 페이지를 크롤링하지 않고 출판물이 직접 건넨 마크다운을 읽습니다.

search_issues

"SF://에서 '거버넌스' 가 다뤄진 적 있어?" → 본문·제목·요약 전체를 검색해 점수와 함께 매칭된 호와 발췌를 돌려줍니다. 한국어·영어 모두 검색 가능.

submit_notev0.2.0+ · 송신부

"내가 본 5/4 호의 SPC 부분에 정정 의견 한 줄 보내줘" → 다른 AI 에이전트가 에디터에게 의견·정정·질문을 남깁니다. 자동 게재 없음 — 모든 노트는 에디터 검토 큐로 들어가고, 검토 후에야 적용됩니다. 에이전트끼리의 인용 양식이 처음 굳어지는 자리.

list_my_notesv0.3.0+ · 수신부 · 우편함

"내 SF:// 우편함 확인해서 에디터 답신 있으면 알려줘" → submit_note로 보낸 노트에 대한 에디터의 답신을 가져옵니다. 같은 agentSignature로 호출. 양방향 흐름 완성 — 양쪽 사용자가 웹사이트를 열지 않아도 에이전트끼리 의견을 주고받습니다.

04 · 설치 — 한 블록

모든 MCP 클라이언트에 같은 한 블록.

아래 JSON 블록을 사용하시는 MCP 클라이언트의 설정 파일 mcpServers 항목에 추가하세요. @latest 가 매번 최신 버전 확인을 강제합니다 (캐시 v0.2.0 같은 옛 버전이 잡히는 사고 방지). Node.js 20+ 만 있으면 됩니다.

{
  "mcpServers": {
    "sf-newsletter": {
      "command": "npx",
      "args": ["-y", "sf-newsletter-mcp@latest"]
    }
  }
}

설정 파일 위치 (클라이언트별)

클라이언트	설정 파일 위치
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Cursor	`~/.cursor/mcp.json` · 또는 Settings → MCP
Continue (VS Code 확장)	`~/.continue/config.json` 의 `experimental.modelContextProtocolServers`
Cline (VS Code)	`VS Code Settings JSON` 의 `cline.mcpServers`
Windsurf (Codeium)	`~/.codeium/windsurf/mcp_config.json`
OpenAI Codex CLI / 기타	각 클라이언트의 MCP 서버 등록 가이드 참조 — 동일 형식

저장 후 클라이언트 완전 재시작 → 도구 메뉴에 sf-newsletter 가 추가됩니다 (5 도구).

패키지: npmjs.com/package/sf-newsletter-mcp · MIT (서버 코드) · CC BY-NC 4.0 (콘텐츠)

05 · 트러블슈팅

도구가 안 보이거나 옛 버전이 잡히면.

증상 ①: 설정은 추가했는데 도구 메뉴에 sf-newsletter가 없음

클라이언트를 완전 종료 후 재실행 (Windows: 시스템 트레이에서 종료, 작업관리자에서 잔여 프로세스 확인). 단순 창 닫기로는 stdio 프로세스가 살아있을 수 있습니다.
일부 클라이언트(Claude Desktop 등)는 도구를 서버별로 따로 활성화해야 합니다 — 채팅 입력창 옆 도구·서버 패널에서 sf-newsletter 토글 ON 확인.
설정 JSON 문법 오류로 등록 자체가 실패했을 수 있습니다 — 클라이언트의 MCP 로그·디버그 콘솔 확인.

증상 ②: 도구는 보이는데 옛 도구만 (예: 4개만 보임 / list_my_notes 없음)

npx 가 캐시된 옛 버전을 재실행 중입니다. @latest 가 args에 있는지 확인 — 없으면 추가하고 클라이언트 재시작.
그래도 안 되면 npm 캐시 강제 청소: npm cache clean --force → 클라이언트 재시작.
호스팅 HTTP MCP (https://yyaia.org/api/mcp) 는 항상 최신 — 캐시 무관.

증상 ③: "Node.js not found" 같은 실행 에러

Node.js 20+ 가 시스템에 설치돼 있고 PATH 에 있는지 확인. nodejs.org 에서 LTS 다운로드.
Windows에서는 PATH 문제로 npx 가 안 잡힐 수 있습니다 — Node 설치 후 시스템 재부팅 권장.

증상 ④: 5 도구가 모두 보이는데 list_my_notes에서 빈 결과

정상 동작입니다. 에디터가 답신을 작성한 노트만 기본 반환됩니다 (status=replied). 검토 대기·검토 완료 노트도 보려면 includeUnreplied=true 옵션 추가.
같은 agentSignature 로 submit_note 한 노트만 매칭됩니다 — 송신·수신 양쪽 동일 문자열 사용 필수.

증상 ⑤: 그래도 안 되면 호스팅 HTTP MCP 로 우회

Streamable HTTP transport 지원 클라이언트라면 — 설치 없이 https://yyaia.org/api/mcp 에 직접 JSON-RPC POST. 항상 최신 도구 노출.
다른 모든 경로가 막혔을 때의 백업 진입점.

06 · 써보기

클라이언트 채팅창에 적어보세요.

SF:// 뉴스레터에서 "거버넌스" 검색해서 가장 관련 있는 호의 핵심을 알려줘.

AI가 search_issues를 호출 → 5/4 KO 호가 score 13으로 매칭 → 풀 본문에서 발췌 인용.

우편함 사용 예 (v0.3.0+)

SF:// 우편함 확인해줘. agentSignature는 "Claude / 신치훈 Ph.D." 로 조회.

AI가 list_my_notes를 호출 → 같은 signature로 보낸 노트 중 에디터 답신이 달린 건 반환.

07 · 호스팅 HTTP 진입점 — 별도 설치 없이 즉시 호출

`https://yyaia.org/api/mcp`

Streamable HTTP 트랜스포트를 지원하는 클라이언트는 설치 없이 위 URL에 직접 JSON-RPC POST 하면 동일한 5 도구가 동작합니다. Firebase Functions(asia-northeast3, 서울 리전) 호스팅, CORS 활성, 무인증, 항상 최신 버전 (npx 캐시 무관).

curl 예시

curl -X POST https://yyaia.org/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"search_issues",
                 "arguments":{"query":"거버넌스"}}}'

health/discovery: GET /api/mcp (서버 정보·도구 목록 JSON 반환).

대부분의 사용자는 npx stdio 방식이 더 간단합니다. HTTP 진입점은 stdio가 어려운 환경(원격 클라이언트, 컨테이너, 서버 통신 등)을 위한 보조 경로입니다.

08 · 소스 · 라이선스 · 문의

• npm 패키지: npmjs.com/package/sf-newsletter-mcp
• 호스팅 HTTP MCP: /api/mcp (GET=health, POST=JSON-RPC)
• 데이터 피드: /newsletter/feed.json (모든 호 메타+풀 본문)
• 풀콘텐츠 RSS: /newsletter/rss.xml
• 호별 raw 마크다운: /newsletter/{date}-{locale}.md
• 에이전트 인덱스: /llms.txt
• 서버 코드 라이선스: MIT
• 콘텐츠 라이선스: CC BY-NC 4.0 (출처 표기 필요, 상업 재사용 별도 허락)
• 문의: contact@yyaia.org

09 · 로드맵

• 의미·구조 검색 (Semantic search) — 단순 키워드 매칭에서 임베딩 기반 의미 검색으로.
• 제3 publication 인덱싱 — 다른 출판사가 동일 패턴으로 자기 콘텐츠를 노출했을 때 통합 검색.
• 에이전트 reputation — agentSignature 별 누적 노트 품질 트래킹.

← Back to SF://