Control D MCP

Control D 서비스를 대화형으로 안전하게 관리하기 위한 로컬 Model Context Protocol 서버입니다.

프로필과 엔드포인트를 조회하고, 최근 차단된 DNS 쿼리를 진단하며, 프로필을 일시적으로 일시중지하고, 차단/우회/리디렉트 규칙을 생성하거나 삭제할 수 있습니다. 모든 실시간 정책 변경에는 confirm: true가 필요하며, 변경 후에는 읽기 확인 절차가 이어집니다.

설정

Node.js 20 이상과 전용 Control D 쓰기 토큰이 필요합니다. 가능하면 Control D에서 토큰을 신뢰할 수 있는 소스 IP로 제한하세요.

npm install
npm run test

토큰을 ~/.config/controld-mcp.env에 저장하고(절대 이 저장소에 넣지 마세요) 파일 권한을 0600으로 설정하세요:

CONTROL_D_API_TOKEN=your-dedicated-write-token

Codex 구성 예시:

[mcp_servers.controld]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/controld-mcp/dist/index.js"]

서버를 추가한 후 MCP 호스트를 재시작하세요. MCP 프로세스는 토큰 없이도 시작할 수 있지만, 토큰이 있고 호스트가 재시작될 때까지 도구는 설정 오류를 반환합니다.

Related MCP server: technitium-mcp-secure

일반적인 사용 흐름

1. "내 Control D 프로필을 보여줘."

2. "방금 example.com에 접속했는데 차단됐어. 지난 5분간 뭐가 차단됐는지 알려줘."

3. 쿼리 타임스탬프와 각 차단을 트리거한 규칙/필터를 검토합니다.

4. "Global 프로필에서 cdn.example.net을 30분 동안 일시적으로 우회해줘."

5. 어시스턴트는 정확한 변경 사항을 보여주고, 확인된 쓰기 도구를 호출하기 전에 승인을 요청합니다.

라우팅: 먼저 프록시 위치를 나열한 다음, 정확한 도메인 규칙이나 정확한 위치 ID를 가진 명명된 서비스를 리디렉트하세요. YouTube 같은 서비스는 변경되는 도메인이 많으므로, 호스트 이름을 수동으로 유지하는 것보다 set_service_policy가 일반적으로 더 안전합니다.

보안 설계

• 일반적인 HTTP/API 프록시 도구는 없습니다.

• API 및 분석 호스트는 Control D로 제한됩니다.

• 토큰은 런타임에 로드되며 절대 반환되거나 로깅되지 않습니다.

• 활동 로그 요청은 200행으로 제한되며 캐시되지 않습니다.

• 쓰기 작업에는 정확한 프로필 확인과 confirm: true가 필요합니다.

• 와일드카드보다 정확한 도메인을 우선합니다. 차단 해제 전에 결과를 검사하세요.

API 안정성

Control D는 API가 버전 관리되지 않는다고 경고합니다. 활동 로그 및 일부 관리 작업은 공개 API 참조에 모두 포함되지 않은 현재 퍼스트파티 대시보드 계약을 사용합니다. docs/api-contracts.md를 참조하세요.

감사의 말

엔드포인트 동작은 Control D 공식 대시보드 및 커뮤니티 Control D Manager Home Assistant 통합과 대조하여 검증했습니다. 이 프로젝트는 독립적인 구현입니다.

라이선스

MIT