Sumi Docs

English | 简体中文

Sumi Docs는 검토된 하나의 문서 코퍼스를 두 소비자에게 제공합니다:

• 사람들은 Astro 및 Starlight 웹사이트를 탐색합니다;

• 에이전트는 읽기 전용 MCP 서버를 통해 동일한 코퍼스를 질의합니다.

검토된 루트 docs/ 트리와 콘텐츠 카탈로그가 의미론적 소스 오브 트루스입니다. 웹사이트와 MCP 서버는 독립적으로 주소 지정 가능한 프로젝션입니다. 에이전트 호스트는 MCP 클라이언트입니다.

소스 저장소와 문서 사이트는 공개되어 있으며 활발히 개발 중입니다. 게시된 npm 패키지, 태그된 GitHub 릴리스 또는 지원되는 바이너리는 없습니다.

사전 요구 사항

• Node.js 25.5.0 이상

• Corepack을 통한 pnpm 10.26.0 또는 packageManager에 선언된 버전

• 저장소 제공 에이전트 호스트 구성을 로드할 때 신뢰할 수 있는 체크아웃

Related MCP server: mcp-docs

첫 실행

pnpm install --frozen-lockfile
pnpm run build
node packages/mcp/dist/index.js doctor --json

Doctor는 기본적으로 프로젝트 상대 경로 또는 외부 소스 플레이스홀더를 보고합니다. 로컬 진단에만 --show-paths를 추가하세요. 해당 출력을 공개 이슈나 빌드 산출물에 첨부하지 마세요.

체크인된 sumi-docs.config.json은 루트 docs/와 예제 OpenAPI 문서를 선택합니다. 다음으로 사람용 사이트를 시작합니다:

pnpm --filter @sumi-os/docs-web dev

http://127.0.0.1:4321을 엽니다. Codex, Claude Code 및 VS Code 프로젝트 어댑터는 에이전트 호스트 통합에 설명되어 있습니다. 이들은 선택적 유지관리자 Skill 없이 네 가지 MCP 도구를 노출합니다.

루프백 Streamable HTTP 엔드포인트에서 동일한 코퍼스를 노출하려면:

node packages/mcp/dist/index.js serve --transport streamable-http

호환되는 MCP 클라이언트를 http://127.0.0.1:3000/mcp에 연결하세요. 정적 웹사이트와 _mcp 코퍼스 프로젝션은 자체적으로 해당 엔드포인트를 실행하지 않습니다.

동일한 검토된 루트 코퍼스를 사용하는 강화된 로컬 컨테이너의 경우:

docker compose up --build

서비스는 http://localhost:3000/mcp에서 MCP를, /healthz에서 활성 상태를, /readyz에서 코퍼스 준비 상태를 노출합니다. Docker는 소스 개발에 선택 사항입니다. 공개 배포에는 여전히 HTTPS 종료와 명시적 Host 정책이 필요합니다.

저장소는 또한 .agents/skills/ 아래에 세 가지 선택적 프로젝트 워크플로를 제공합니다: $sumi-docs-use는 설정 및 운영용, $sumi-docs-pr은 제안 및 풀 리퀘스트 준비용, $sumi-docs-audit은 읽기 전용의 증거 기반 저장소 및 릴리스 감사용입니다. 이들은 작업을 안내하지만 MCP를 대체하거나 원격 변경 사항을 게시하지는 않습니다.

작업 공간

apps/web/                   Astro/Starlight site and corpus publisher
packages/mcp/               stdio and Streamable HTTP MCP server and CLI
packages/corpus-contract/   manifest schemas and conformance fixtures
docs/                       product handbook and default corpus
.agents/skills/             optional project usage and contribution workflows

로컬 운영과 기본 Pages 전용 게시에는 런타임 비밀이 필요하지 않습니다. SITE_URL은 릴리스 사이트 후보에만 필요합니다. 선택적 프로덕션 Streamable HTTP 서비스를 활성화하려면 보호된 production-mcp 환경에 검토된 엔드포인트 변수와 SSH 자료가 필요합니다. 컨테이너는 문서화된 SUMI_DOCS_* 배포 변수를 허용합니다. 생성된 출력, 로컬 상태, 로그, 캐시 및 .env 파일은 무시됩니다.

패키지별 지침은 각 작업 공간에 있습니다. 활성 아키텍처 결정은 소유 작업 공간의 docs/decisions/ 디렉터리에 있습니다. 루트 핸드북은 결정 기록을 중복하지 않고 사용자에게 보이는 결과를 제시합니다.

소스 및 사이트 공개는 태그, 패키지 또는 바이너리를 게시하지 않습니다. 해당 산출물은 문서화된 릴리스 게이트의 적용을 받습니다.