IntentCP — 말로 내린 명령을 안전하게 기기 제어로 바꾸는 중계 서버

프레임워크 없이 자연어 명령을 검증 가능한 실행 포맷으로 한 번 바꿔, 서버가 정의된 동작만 실행하도록 만든 개인 오픈소스 프로젝트입니다. LLM 해석은 폰에 맡기고 서버는 제약된 실행과 중계만 담당하도록 책임을 분리했습니다.

집에 별도의 LLM·GPU 서버를 두지 않고, 폰의 Apple Intelligence와 iOS 단축어만으로 자연어 명령이 실제 기기 동작으로 이어지게 하는 구조입니다.

배경·과제

• 자연어를 서버가 그대로 실행하면 의도와 다르게 움직일 위험이 있습니다. 말과 실행 사이에 검증 가능한 중간 표현을 넣어 통제된 범위 안에서만 동작하도록 하는 구조가 필요했습니다.

• 스마트홈 음성 제어를 하려면 일반적으로 집에 상시 구동되는 GPU 서버가 필요합니다. 1인 자취 환경에서는 그런 서버 없이 가볍게 돌릴 수 있는 인프라를 직접 짜보고 싶었습니다.

수행·기여

• 의도 해석과 실행을 분리했습니다. 자연어를 약속된 실행 포맷(Control URL)로 바꾸는 단계(LLM), 정의된 동작만 수행하는 실행 코어(FastAPI), 그리고 실행 결과를 한 줄로 요약하는 피드백(LLM) 흐름을 직접 설계했습니다. 자연어 처리를 폰 쪽에 두고 서버는 최소한의 역할만 하도록 했습니다.

• 자연어를 그대로 실행하지 않는 원칙을 뒀습니다. 자연어 명령은 바로 기기를 움직이지 않고, 먼저 Control URL 형식(예: 거실등 켜기)으로 정규화됩니다. 서버는 이 형식에 정의된 동작만 실행하므로 예외 동작이 생기지 않습니다.

• 모든 호출을 같은 실행 포맷으로 통합했습니다. Siri든 단축어 자동화든 Control URL 하나의 표준 경로를 거칩니다. 켜기·끄기·밝기·상태 조회·시퀀스 제어를 같은 포맷에서 다룹니다.

• 경량 코어 인프라를 구현했습니다. Python·FastAPI 기반 REST 서버로, GPU나 로컬 LLM 서버 없이 저사양 미니 서버에서 24시간 구동됩니다. 자연어 해석은 폰의 Apple Intelligence·iOS 단축어가 맡고, 서버는 실행과 중계에만 집중합니다. 설정 웹 패널과 CLI 도구를 포함해 코어 서버·단축어·프롬프트 구성을 한 저장소(monorepo)로 관리했습니다.

성과

• GitHub에 단독으로 공개했으며(2025.12.08 시작), 유튜브 채널 영상 노출 이후 22 stars를 얻었습니다(2026.05 기준).

• 개인 프로젝트로, 실사용자 규모보다는 프레임워크 없이 의도→안전 실행→피드백 흐름을 설계해 본 제작 과정에 의미를 두었습니다. 현재도 본인 자취 환경 자동화에 직접 쓰며 다듬고 있습니다.