TableCloth.Mcp 0.3.0

TableCloth MCP

식탁보(TableCloth)의 "발견과 안전 실행환경 인계" 레이어를 MCP 서버로 제공합니다. 사용자의 상황이나 질의를 받아 지금 필요한 한국 공공(e-Gov)이나 금융 사이트를 찾아주고, 보안프로그램 설치의 번거로움 없이 깨끗한 일회용 Windows Sandbox로 그 사이트를 열어 줍니다.

이 서버가 하는 일은 보안프로그램 때문에 생기는 불편을 줄이고 알맞은 사이트를 찾아 주는 데까지입니다. 로그인이나 인증, 실제 업무 자동화(RPA)는 하지 않으며, 그 부분은 사용자가 직접 진행합니다.

설치

Claude Desktop이라면 원클릭 확장(.mcpb)이 가장 간편하고, 그 외 클라이언트는 MCP 설정에 npx나 dnx 실행을 넣으면 됩니다. 모두 동일한 서버입니다.

Claude Desktop 확장 (.mcpb, 원클릭)

GitHub Release에서 tablecloth-mcp.mcpb를 받아 Claude Desktop에 끌어다 놓거나 더블클릭하면 설치됩니다. Claude Desktop이 번들한 Node로 실행되는 순수 JS 번들이라 별도 런타임 설치가 필요 없고, 네이티브 바이너리가 없어 서명/공증이나 확장 재설치 시 잠금 문제도 없습니다(Windows, macOS). MCP 설정을 직접 편집할 필요도 없습니다. macOS에서의 launch_sandbox는 macSandbox가 필요합니다.

npx로 실행 (Node 사용자, .NET 불필요)

순수 JS 패키지라 어떤 OS든 Node만 있으면 동작합니다(네이티브 바이너리 없음). @latest를 붙인 이유는 아래 업데이트 참고입니다. npx는 버전을 명시하지 않으면 캐시된 옛 버전을 계속 쓸 수 있어, 새 버전을 잘 받도록 @latest를 권합니다.

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

전역으로 설치해서 쓸 수도 있습니다.

npm install -g tablecloth-mcp
tablecloth-mcp

dnx로 실행 (.NET 10 SDK 사용자)

NuGet 툴 패키지를 별도 설치 없이 실행합니다.

{
  "mcpServers": {
    "tablecloth": { "command": "dnx", "args": ["TableCloth.Mcp", "--yes"] }
  }
}

전역 도구로 설치해서 쓸 수도 있습니다.

dotnet tool install -g TableCloth.Mcp
tablecloth-mcp

npx(순수 JS)는 Node가 있는 모든 OS에서, dnx는 .NET 10 SDK가 있는 모든 OS에서 동작합니다. 검색과 generate_wsb는 모든 OS에서 되고, launch_sandbox의 자동 실행은 러너가 있는 OS(Windows는 Windows Sandbox, macOS는 macSandbox)에서만 됩니다.

업데이트

MCP 서버는 클라이언트가 시작할 때 프로세스로 떠서 실행되고, 실행 중에는 새 버전으로 교체되지 않습니다. 그래서 새 버전은 클라이언트를 다시 시작해 서버를 새로 띄울 때 반영됩니다. Claude Desktop은 앱을 재시작해야 하고, Claude Code는 세션을 새로 시작하면 됩니다.

• 무엇이 자동으로 갱신되나: 카탈로그(사이트, 정책, 보안패키지 목록)는 서버가 런타임에 라이브로 받아오므로, 새 서비스나 정책 추가 같은 변경은 서버 버전을 올리지 않아도 바로 반영됩니다. 서버 버전 교체가 필요한 건 도구 동작 변경이나 버그 수정 같은 코드 변경뿐입니다.
• npx: 버전 없이 쓰면 캐시된 옛 버전을 계속 쓸 수 있어 tablecloth-mcp@latest를 권합니다. 그래도 npm 캐시 영향이 남을 수 있으니, 확실히 최신으로 받으려면 클라이언트 재시작 전에 npm cache clean --force를 한 번 해도 됩니다.
• dnx: 버전을 명시하지 않으면 실행할 때마다 최신 버전을 해석해 받습니다. 갱신 적시성이 중요하면 dnx 쪽이 더 유리합니다.
• 결정론이 필요하면(기업 배포 등) 버전을 고정하고(tablecloth-mcp@0.1.3, dnx는 --version) 의도적으로 올리는 방법도 있습니다. 갱신은 수동이 되지만 예측 가능합니다.

도구

예시 흐름 (연말정산)

1. search_services("연말정산") 또는 search_services("홈택스")로 홈택스 등 후보와 id를 얻습니다.
2. launch_sandbox(["<홈택스 id>"])를 호출하면 보안프로그램이 갖춰진 일회용 샌드박스가 뜨고 사이트가 열립니다.
3. 인증서나 간편인증, 연말정산간소화 조회와 발급은 사용자가 직접 진행합니다.

TableCloth 리포지터리에 의존하지 않습니다

런타임에 공개된 자산만 소비합니다.

생성되는 .wsb는 무설치 Express 방식(PARAMETERIZED_WSB_SPEC.md 0.5절)을 따르며, 사이트 사전선택은 TABLECLOTH_SITE_IDS 환경변수 채널로 전달됩니다.

사용 팁: TableCloth 스킬로 자동 연결하기

정부 정책이나 금융 상품, 시사 현안을 이야기하다가 "그거 신청할래" 정도로만 말해도 이 서버로 연결되게 하려면, 저장소의 SKILL.md를 Agent Skill로 설치하는 방법을 권합니다. 이 스킬은 사용자의 행동 의도(신청, 가입, 접속, 이용)를 포착해 "샌드박스"라는 말이 없어도 TableCloth 도구로 공식 사이트를 안전한 샌드박스에서 열도록 안내합니다. 다른 검색 MCP(예: 웹 검색)와 함께 쓰면 정보 탐색은 그쪽으로 가고 실제 신청과 이용은 이 서버로 갈라집니다.

설치는 SKILL.md를 ~/.claude/skills/tablecloth/SKILL.md에 두면 됩니다. 폴더 이름 tablecloth가 스킬 이름이 됩니다. Claude Desktop이나 claude.ai에서는 각 앱의 스킬 설정에서 관리합니다.

도구 설명과 서버 instructions에도 같은 의도가 심어져 있어 스킬 없이도 어느 정도 연결되지만, 스킬을 더하면 더 안정적으로 라우팅됩니다. launch_sandbox의 실제 실행 환경은 아래 제약을 참고하세요.

제약

• launch_sandbox의 자동 실행 러너는 Windows에서는 Windows 11의 "Windows Sandbox" 선택적 기능, macOS에서는 macSandbox(Apple Silicon, macOS 26)입니다. 리눅스처럼 기본 러너가 없는 OS에서는 TABLECLOTH_WSB_RUNNER 환경변수에 .wsb 경로를 첫 인자로 받는 러너 명령(예: QEMU 기반 스크립트)을 지정하면 자동으로 실행합니다. 이 환경변수는 모든 OS에서 기본값보다 우선하므로 사용자 지정 러너를 붙일 때도 씁니다. 지정이 없으면 generate_wsb로 .wsb를 받아 실행하면 됩니다.
• 인증이 필요한 동작은 자동화하지 않습니다. 무설치 방식은 호스트 파일 접근이 없어 파일 인증서를 들일 수 없으므로 모바일이나 간편인증을 전제로 합니다.
• 카탈로그에 없는 서비스는 실행 대상이 아닙니다. 제보는 식탁보 카탈로그로 하면 됩니다.

문제 해결

연결이 안 되거나 응답이 오지 않으면 TROUBLESHOOTING.md를 참고하세요.

가장 흔한 원인은 Claude Desktop이 claude_desktop_config.json과 별개로 캐시해 둔 옛 MCP 서버 등록입니다. 설정 파일을 고쳐도 지워지지 않아, 같은 이름으로 등록해 둔 옛 서버(예: 로컬 개발 빌드나 테스트용)가 대신 호출되어 엉뚱한 프로세스가 뜨거나 프롬프트가 몇 분씩 멈춥니다. 해결은 Settings의 Developer(개발자 도구)에서 목록에 보이는 MCP 서버를 휴지통 아이콘으로 직접 삭제하고(파일 수정만으로는 안 지워짐), 확장을 모두 제거한 뒤 Claude Desktop을 완전히 종료(트레이 종료, macOS는 Cmd+Q)했다가 다시 시작하는 것입니다.

릴리스

버전 태그(vX.Y.Z)를 밀면 .github/workflows/release.yml가 같은 버전으로 여러 곳에 함께 게시합니다.

• npm에 순수 JS 패키지 tablecloth-mcp를 올립니다(네이티브 바이너리 없음).
• NuGet에 TableCloth.Mcp 툴 패키지(C#)를 올립니다.
• GitHub Release에 nupkg와 Claude Desktop 확장 .mcpb(Node 번들)를 첨부합니다.
• 공식 MCP Registry에 서버 메타데이터(server.json)를 게시합니다. GitHub OIDC로 인증하므로 시크릿이 필요 없고, VS Code나 Cursor 같은 다른 클라이언트가 이 색인으로 서버를 발견합니다.

npm과 NuGet은 OIDC Trusted Publishing으로 게시되어 장기 토큰을 저장하지 않으며, npm 패키지에는 provenance가 자동으로 붙습니다. 변경 이력은 CHANGELOG.md에 정리하고, 새 버전을 낼 때는 거기에 ## [X.Y.Z] 섹션을 추가한 뒤 태그를 밀면 그 내용이 GitHub Release 노트가 됩니다.

개발

레인별로 두 구현이 있고, 둘 다 shared/를 단일 진실 원천으로 소비합니다(SPEC.md).

• .mcpb + npm 레인: node/ 의 Node/TS 구현(순수 JS). cd node && npm ci && npm run build.
• NuGet 도구(dnx) 레인: 이 리포 루트의 C# 구현. dotnet build -c Release.

두 구현의 동등성은 conformance 하네스로 검증합니다: cd node && npm run conformance (리포 루트에서 dotnet build -c Release, node에서 npm run build 선행). CI가 매 빌드에서 실행합니다.

Privacy Policy

이 서버는 개인 데이터나 대화 내용, 사용 통계를 수집하거나 저장하거나 전송하지 않습니다. 공개 카탈로그(yourtablecloth.app)와 GitHub Release 자산만 읽어오며, 사용자 데이터를 함께 보내지 않습니다. launch_sandbox는 로컬에서 샌드박스를 띄우고 임시 .wsb 파일만 만들며, 로그인과 인증은 사용자가 샌드박스 안에서 직접 하고 서버는 관여하지 않습니다. 서버는 무상태이며 종료 후 데이터를 남기지 않습니다. 전문은 PRIVACY.md를 참고하세요.

라이선스

본 프로젝트 TableCloth와 동일하게 듀얼 라이선스입니다.

• AGPL-3.0-or-later (LICENSE-AGPL)로 오픈소스 이용이 가능합니다.
• 상업적 이용으로 AGPL 의무를 원치 않으면 개발자(Jung Hyun, Nam, rkttu at rkttu dot com)와 협의하는 Commercial 라이선스(LICENSE-COMMERCIAL)를 쓰면 됩니다.

이 서버는 stdio 로컬 프로세스로 동작하고 MCP 클라이언트와는 별도 프로세스로 프로토콜을 통해서만 통신하므로, 호출하는 쪽에 AGPL 의무가 전파되지 않습니다.