ondocs
문서에 대한 오픈 소스 Ask AI를 구현하세요. 자체 모델 키로 인용된 답변과 코딩 에이전트를 위한 MCP 서버가 하나의 인덱스에서 제공됩니다. 이 인덱스는 사용자의 Starlight, Docusaurus 또는 VitePress 사이트로 구축됩니다. 벤더 종속성이나 벡터 데이터베이스가 필요 없습니다.
자체 개발자 문서를 운영하는 제품, API 및 플랫폼 기업의 팀을 위한 것입니다. 호스팅된 어시스턴트 없이도 Ask AI 기능을 원하는 경우에 적합합니다.
CI
npm
Script tag: 3.5 KB gzipped
License: MIT
Types
다음 모델로 답변 제공
OpenAI
Anthropic
Google Gemini
xAI Grok
Workers AI
any AI SDK provider
Deploy to Cloudflare
이 사이트의 MCP 서버를 통해 에디터에서 문서에 대해 질문하세요:
Cursor
VS Code
Claude Code
Claude
웹사이트: ondocs.vercel.app의 문서(docs)는 OpenAI를 사용하여 답변하며, /api/mcp에서 에이전트를 제공합니다. 이전 이름은 ask-my-site였습니다 (변경 사항).
피드백 요청: 출시 피드백 스레드에서 문제가 발생하는 부분을 알려주거나, 로드맵에서 다음 계획을 확인하거나, 좋은 첫 이슈를 맡아보세요. ondocs가 유용하다면, 별점(star)을 눌러 다른 사람들이 이 프로젝트를 발견하는 데 도움을 줄 수 있습니다.
<!-- npm-readme:video -->
<sub>실시간 데모**: 인용된 답변이 스트리밍되며, 해당 내용이 나온 섹션을 열어주고, 마지막으로 한 줄 설정(one-line setups)까지 제공합니다.</sub>
<!-- npm-readme:image
<p align="center">
<a href="https://ondocs.vercel.app"><img src="https://raw.githubusercontent.com/dgesteves/ondocs/HEAD/.github/assets/demo.webp" width="100%" alt="The live demo: a question about the docs, a streamed answer with numbered citations, a citation opening the exact section of the FAQ page, then the Ask button on that page answering how to add it to Starlight with the exact config. Last, the one-line setup for Docusaurus, Starlight and any other site."></a>
</p>
<sub>실시간 데모**: 인용된 답변이 스트리밍되며, 해당 내용이 나온 섹션을 열어주고, 마지막으로 한 줄 설정(one-line setups)까지 제공합니다.</sub>
-->
실시간 데모: Starlight, Docusaurus, 그리고 VitePress에서 실시간 데모를 확인할 수 있으며, 각각은 자체 플러그인으로 구축된 실제 문서 사이트입니다.
제공되는 기능
귀하의 사이트로 구축된 하나의 인덱스, ask-index.json,가 세 가지 요소에 데이터를 공급합니다:
- 사람들을 위한 질의 상자(Ask box for people). 모델로부터 짧은 답변을 스트리밍하고 정확한 섹션에 대한 번호가 매겨진 인용(citation)을 제공하는 ⌘I 대화 상자입니다. 주제에서 벗어난 질문의 경우, 모델이 호출되기 전에 "모릅니다(I don't know)"라는 응답을 받게 됩니다. 페이지에는 버튼만 로드되고, 대화 상자는 첫 사용 시에 로드됩니다.
- 에이전트를 위한 MCP 서버(MCP server for agents). 동일한 인덱스에 대한
search, fetch, 및 list_pages 기능을 제공하며, 코딩 에이전트와 ChatGPT를 위해 설계되었습니다. 에이전트는 자체 모델을 가져오며, 기본값인 키워드 검색은 모델을 전혀 호출하지 않습니다.
- 빌드 시 생성되는
llms.txt, llms-full.txt, 그리고 모든 페이지의 .md 사본입니다.
검색(Search)은 배포하는 단일 함수 내 메모리에서 실행됩니다: BM25와 벡터를 상호 순위 융합(reciprocal rank fusion)으로 병합하여 사용합니다.
설정 선택하기 (Pick your setup)
모든 답변은 사이트 옆에 단일 함수로 배포하는 엔드포인트에서 제공되며, 기본적으로 속도 제한됩니다. npx ondocs init을 사용하면 Vercel, Netlify, Cloudflare 또는 GitHub Pages(Workers AI를 사용하여 API 키 없이 Workers로 응답)용으로 설정을 작성합니다. 자세한 내용은 배포하기를 참조하세요.
Starlight. npm i ondocs ai @ai-sdk/openai를 실행한 후 다음을 추가합니다:
import starlight from '@astrojs/starlight';
import ondocs from 'ondocs/starlight';
...
astro build가 완료되면, 페이지들을 dist/ask-index.json에 인덱싱하고, llms.txt와 .md 페이지를 작성하며, ⌘I를 가진 "Ask AI" 버튼을 추가합니다. 정적 사이트인가요? npx ondocs init을 사용하세요. SSR 어댑터인가요? 할 일이 없습니다.
Docusaurus. npm i ondocs ai @ai-sdk/openai @radix-ui/react-dialog cmdk를 실행한 후 다음과 같이 추가합니다:
// docusaurus.config.ts
export default { plugins: ['ondocs/docusaurus'] };
docusaurus build 실행 후에도 동일하게 build/ 디렉터리에 결과물이 생성됩니다.
Next.js. OPENAI_API_KEY를 설정한 후, 다음 명령어를 사용하여 콘텐츠를 인덱싱합니다: npx ondocs index ./content --base-url /docs --llms-txt public, 그리고:
import { openai } from '@ai-sdk/openai';
import { createAskHandler } from 'ondocs/server';
...
이후 레이아웃에 다음 코드를 사용하여 대화형 위젯(dialog)을 렌더링하고, 두 개의 스타일시트를 적용합니다:
import { AskDialog } from 'ondocs/react';
import 'ondocs/react/styles.css';
...
다른 모든 사이트. 빌드된 HTML을 인덱싱하고, npx ondocs init으로 엔드포인트를 작성한 다음, 스크립트 태그를 추가합니다:
npx ondocs index public -o public/ask-index.json
npx ondocs init --out public
...
GitHub Pages 프로젝트 사이트(https://user.github.io/repo)의 경우, index 명령어에 --base-url /repo를 추가해야 합니다.
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/embed.global.js" defer></script>
키 없이 사용해 보기. npx ondocs index ./docs -e mock을 실행한 다음, npx ondocs dev를 실행하면 로컬호스트에서 ask 엔드포인트와 MCP 서버가 모의(mock) 모델과 함께 제공되며, 이 모델은 문서를 인용합니다. 자세한 내용은 로컬에서 사용해 보기를 참조하세요.
에이전트(agents)용
동일하게 인덱싱하여 createMcpHandler와 함께 에이전트에게 제공할 수 있습니다:
import { createMcpHandler } from 'ondocs/server';
import index from '../../../ask-index.json';
...
claude mcp add --transport http acme-docs https://docs.acme.dev/api/mcp
codex mcp add acme-docs --url https://docs.acme.dev/api/mcp
gemini mcp add --transport http --scope user acme-docs https://docs.acme.dev/api/mcp
- 프로토콜(Protocol). MCP는 2026-07-28 버전이며,
initialize로 시작하는 클라이언트의 경우 2025-11-25부터 2024-11-05까지 지원하며, 공식 TypeScript 클라이언트로 테스트되었습니다.
- 도구(Tools).
search는 스니펫과 앵커 URL이 포함된 순위가 매겨진 섹션을 반환하며, fetch는 ChatGPT의 커넥터가 기대하는 방식대로 페이지 또는 섹션을 마크다운(Markdown) 형식으로 가져옵니다.
- 품질(Quality). docusaurus.io의 문서에서 키워드 검색은 저희가 문서 용어로 작성한 22개의 에이전트 스타일(agent-style) 질의 중 22개 모두를 상위 세 개에 배치하며, 사람이 질문하는 방식으로는 22개 중 20개를 찾았습니다 (최상의 경우이며 CI에서 확인됨: 질의). 독자 본인의 단어로는 더 자주 발견되지 않습니다 (실제 Stack Overflow 질문).
- 사용자 문서(On your docs). 플러그인의
mcp 옵션을 사용하면 페이지에 'Cursor / VS Code / Claude에 추가(Add to)' 블록을 표시할 수 있습니다.
- llms.txt. 플러그인은 기본적으로 이 파일을 작성하며, CLI는
--llms-txt <디렉토리명(dir)> 옵션을 사용합니다.
MCP 서버와 llms.txt 및 마크다운 페이지를 참조하십시오.
비용 및 안전 기본 설정 (Cost and safety defaults)
- 질문 하나당 비용은 임베딩 호출(embedding call) 1회와 모델 호출(model call) 1회를 소모하며, 최대 8,000자 분량의 출처가 입력되고 800 토큰이 출력됩니다. 후속 질문을 작성할 때는 추가적인 짧은 호출(short call)이 필요합니다. 문서에서 다루지 않는 대부분의 질문은 모델에 도달하기 전에 중단되지만, 일반 프로그래밍 질문처럼 페이지와 충분한 단어를 공유하는 질문은 여전히 모델에 도달할 수 있습니다.
- **에이전트의 검색 비용(agent's search costs)**은 모델 호출을 소모하지 않거나,
embeddingModel을 사용하여 임베딩 호출 1회를 소모합니다.
- 속도 제한(Rate limits)은 기본적으로 활성화되어 있습니다: 클라이언트 IP당, 서버 인스턴스당 분당 질문 10회와 도구 호출(tool calls) 60회가 제한됩니다. Vercel 외부에서 플랫폼의 클라이언트 IP 헤더를 지정해야 합니다.
- **
budget**은 전체 엔드포인트에 대해 UTC 일별로 질문 및 모델 토큰을 제한하며, **answerCache**는 반복된 질문에 대해 모델 호출 없이 답변하고, **challenge**는 선택적인 Turnstile 봇 확인 절차를 추가합니다.
- **요청(Requests)**은 JSON 형식이어야 하며 본문 크기가 제한됩니다. 모델 오류는 가려지며(masked); 답변은 HTML이 아닌 텍스트로 렌더링되고 기본적으로 출처에만 링크합니다.
- 모델 제공업체(model provider)에서 지출 한도를 설정하세요. 이것이 유일한 하드 캡(hard cap)입니다. 속도 제한 및 보안을 참조하십시오.
비교 방법
