BaaS-MCP

Instructions

Implementation Reference

• src/tools/document-search.tools.ts:8-105 (handler)

  Handler function that implements the core logic of the 'search-documents' tool. It processes search parameters (keywords or query), calls repository.searchDocumentsAdvanced, formats results into a markdown response with document details, scores, and previews, or returns helpful error messages if no results.
  handler: async (params: SearchDocumentsParams): Promise<CallToolResult> => { try { const { keywords, query, searchMode = SearchMode.BALANCED, limit = 5 } = params; let finalSearchQuery = ''; let finalKeywords: string[] = []; // keywords 배열이 있으면 우선 사용 if (keywords && keywords.length > 0) { finalKeywords = keywords.filter(k => k.trim().length > 0); finalSearchQuery = finalKeywords.join(' '); } // 폴백: query 문자열 사용 else if (query && query.trim().length > 0) { finalSearchQuery = query.trim(); // query를 간단히 키워드로 분할 finalKeywords = query.toLowerCase() .replace(/[^\w\s가-힣]/g, ' ') .split(/\s+/) .filter(term => term.length > 1); } // 둘 다 없으면 에러 else { return { content: [ { type: "text", text: `검색 키워드가 필요합니다. 다음과 같이 사용해주세요:\n\n키워드 배열 사용 (권장):\n- keywords: ['로그인', 'React']\n- keywords: ['JWT', '토큰']\n- keywords: ['쿠키', '설정']\n\n문장 사용 (폴백):\n- query: "React 로그인 컴포넌트"\n- query: "JWT 토큰 설정"\n\n사용 가능한 검색 키워드:\n- API 관련: login, signup, authentication, jwt, token\n- 프레임워크: react, nextjs, javascript\n- 보안: security, cors, cookie, validation\n- 에러: error, troubleshooting, debugging` } ] }; } // 새로운 고급 검색 기능을 기본으로 사용 const results = repository.searchDocumentsAdvanced({ query: finalSearchQuery, limit: Math.min(limit, 10), searchMode: searchMode, useWeights: true, useSynonyms: true, // minScore 제거: BM25Calculator의 상대적 필터링만 사용 }); if (results.length === 0) { const searchTerm = finalKeywords.length > 0 ? finalKeywords.join(', ') : finalSearchQuery; return { content: [ { type: "text", text: `검색어 "${searchTerm}"에 대한 관련 문서를 찾을 수 없습니다.\n\n**AIApp BaaS 인증 시스템 문서는 다음 주제로 제한됩니다:**\n\n📚 **사용 가능한 문서 주제:**\n• **로그인 구현**: React/JavaScript 완전 구현 가이드\n• **회원가입 구현**: React/JavaScript 완전 구현 가이드\n• **로그아웃 구현**: React/JavaScript 완전 구현 가이드\n• **사용자 정보**: React/JavaScript 완전 구현 가이드\n• **에러 처리**: 모든 ServiceException과 클라이언트 처리 패턴\n• **보안**: 쿠키, CORS, XSS 방지 설정\n• **통합 가이드**: 빠른 시작 및 인증 플로우\n\n🔍 **권장 검색 키워드:**\n• 로그인: ['로그인', 'React'], ['login', 'javascript']\n• 회원가입: ['회원가입', 'signup'], ['validation', 'form']\n• JWT 토큰: ['JWT', '토큰'], ['authentication', 'token']\n• 에러 처리: ['에러', 'error'], ['ServiceException', 'validation']\n• 보안 설정: ['쿠키', '보안'], ['cors', 'security']\n\n💡 **Tip**: 구체적인 기능과 구현 방식을 함께 검색하면 더 정확한 결과를 얻을 수 있습니다.` } ] }; } const searchTerm = finalKeywords.length > 0 ? finalKeywords.join(', ') : finalSearchQuery; let responseText = `"${searchTerm}" 검색 결과 (${results.length}개 문서):\n\n`; results.forEach((result, index) => { const doc = result.document; responseText += `## ${index + 1}. ${doc.getTitle()}\n`; responseText += `**문서 ID**: ${doc.getId()}\n`; responseText += `**URL**: ${doc.getUrl()}\n`; responseText += `**설명**: ${doc.getDescription()}\n`; responseText += `**관련도 점수**: ${result.score.toFixed(2)}\n\n`; if (result.relevantChunks.length > 0) { responseText += `**관련 내용**:\n`; result.relevantChunks.forEach((chunk, chunkIndex) => { responseText += `${chunkIndex + 1}. ${chunk.substring(0, 200)}${chunk.length > 200 ? '...' : ''}\n\n`; }); } responseText += `---\n\n`; }); responseText += `💡 **Tip**: 더 자세한 내용은 \`get-document-by-id\` 도구에 위에 표시된 **문서 ID**를 사용하여 전체 문서를 조회하세요.\n예: get-document-by-id를 사용할 때 id 파라미터에 위 검색 결과의 문서 ID 값을 입력하세요.`; return { content: [ { type: "text", text: responseText } ] }; } catch (error) { return { content: [ { type: "text", text: `문서 검색 중 오류가 발생했습니다: ${error instanceof Error ? error.message : String(error)}` } ], isError: true }; } }
• src/server.ts:51-76 (registration)

  Registration of the 'search-documents' tool in the MCP server using server.tool(), providing name, description, input schema (SearchDocumentsSchema), and the handler function.
  server.tool( "search-documents", `BaaS 인증 시스템의 기능별 구현 가이드를 키워드로 검색합니다. ⚠️ **중요**: 이 도구를 사용하기 전에 먼저 \`get-project-config\`를 실행하여 필수 구현 규칙을 확인하세요. 🔍 **검색 범위**: 기능별 구현 가이드만 검색 대상 (공통 규칙 문서는 get-project-config에서 제공) 🎯 **검색 가능한 구현 가이드**: - 로그인 구현: keywords=['로그인', 'React'] - API + React + JavaScript 완전 구현 - 회원가입 구현: keywords=['회원가입', 'signup'] - API + 클라이언트 + 유효성 검사 - 사용자 정보: keywords=['사용자', '정보'] - API + 상태 관리 + 에러 처리 - 로그아웃 구현: keywords=['로그아웃', 'logout'] - API + 세션 정리 + 보안 💡 **사용법**: - 키워드 배열: keywords=['JWT', '토큰'], keywords=['validation', 'form'] - 문장 검색: query="React 로그인 구현" 📌 **구현 시 필수 적용 사항** (get-project-config에서 확인): - credentials: 'include' 설정 - result: "SUCCESS"/"FAIL" 응답 형식 - 조건부 렌더링 사용 (CSS display 속성 금지) - HttpOnly 쿠키 자동 관리`, SearchDocumentsSchema, searchDocumentsTool.handler );
• src/schema/tool-schemas.ts:7-33 (schema)

  Zod-based input schema definition for the 'search-documents' tool, defining parameters like keywords (array), optional query, searchMode, and limit with descriptions and constraints.
  export const SearchDocumentsSchema = { keywords: z .array(z.string()) .describe("검색할 키워드 배열. 예: ['로그인', 'React'], ['JWT', '토큰'], ['쿠키', '설정']"), query: z .string() .optional() .describe("키워드 배열 대신 사용할 검색 문장 (비권장). 예: 'React 로그인 컴포넌트'"), searchMode: z .nativeEnum(SearchMode) .default(SearchMode.BALANCED) .optional() .describe(`검색 모드에 따라 결과의 관련성과 정확도가 달라집니다. 검색 모드: - broad: 폭넓은 결과 (관련성 낮아도 포함, 개념 탐색 시) - balanced: 균형잡힌 결과 (일반적인 검색, 기본값) - precise: 정확한 결과만 (정확한 답변 필요 시)`), limit: z .number() .int() .min(1) .max(10) .default(5) .optional() .describe("반환할 검색 결과 수 (기본값: 5, 최대: 10)") };