get-document-by-id

Instructions

Implementation Reference

• src/tools/document-search.tools.ts:109-187 (handler)

  Factory function that creates the tool object with the handler for 'get-document-by-id'. The handler fetches the document by ID from the repository, replaces project ID placeholders, adds metadata if requested, suggests similar documents, and returns formatted text content.

  export function createGetDocumentByIdTool(repository: BaaSDocsRepository, projectId?: string | null) {
    return {
      handler: async (params: GetDocumentByIdParams): Promise<CallToolResult> => {
        try {
          const { id, includeMetadata = false } = params;
          
          const document = repository.getDocumentById(id);
          
          if (!document) {
            return {
              content: [
                {
                  type: "text",
                  text: `ID ${id}에 해당하는 문서를 찾을 수 없습니다. search-documents를 사용하여 먼저 문서를 검색해보세요.`
                }
              ]
            };
          }
  
          let responseText = `# ${document.getTitle()}\n\n`;
          
          if (includeMetadata) {
            responseText += `**문서 정보**:\n`;
            responseText += `- ID: ${document.getId()}\n`;
            responseText += `- URL: ${document.getUrl()}\n`;
            responseText += `- 설명: ${document.getDescription()}\n`;
            responseText += `- 키워드: ${Array.from(document.getKeywords()).slice(0, 10).join(', ')}\n\n`;
            responseText += `---\n\n`;
          }
          
          let contentText = document.getContent();
  
          // Project ID 플레이스홀더 교체
          if (projectId) {
            // [PROJECT_ID] 플레이스홀더를 실제 값으로 교체
            contentText = contentText.replace(/\[PROJECT_ID\]/g, projectId);
            
            // 문서 상단에 설정 정보 추가
            responseText += `> 📌 **현재 Project ID**: \`${projectId}\`\n> 아래 코드에서 [PROJECT_ID]가 자동으로 교체되었습니다.\n\n`;
          } else {
            // Project ID가 설정되지 않은 경우 안내
            responseText += `> ⚠️ **Project ID 미설정**: Claude Desktop 설정에서 --project-id를 추가하세요.\n> 아래 코드의 [PROJECT_ID]를 실제 값으로 교체해야 합니다.\n\n`;
          }
  
          responseText += contentText;
  
          // Suggest similar documents
          const similarDocs = repository.getSimilarDocuments(document, 3);
          if (similarDocs.length > 0) {
            responseText += `\n\n## 관련 문서\n\n`;
            similarDocs.forEach((similarDoc, index) => {
              responseText += `${index + 1}. **${similarDoc.getTitle()}** (ID: ${similarDoc.getId()})\n`;
              responseText += `   - ${similarDoc.getDescription()}\n`;
              responseText += `   - ${similarDoc.getUrl()}\n\n`;
            });
          }
  
          return {
            content: [
              {
                type: "text",
                text: responseText
              }
            ]
          };
        } catch (error) {
          return {
            content: [
              {
                type: "text",
                text: `문서 조회 중 오류가 발생했습니다: ${error instanceof Error ? error.message : String(error)}`
              }
            ],
            isError: true
          };
        }
      }
    };
  }

• src/schema/tool-schemas.ts:38-48 (schema)

  Zod schema defining input parameters for the get-document-by-id tool: required 'id' (number) and optional 'includeMetadata' (boolean).

  export const GetDocumentByIdSchema = {
    id: z
      .number()
      .int()
      .describe("조회할 문서의 ID (search-documents 결과에서 확인 가능)"),
    includeMetadata: z
      .boolean()
      .default(false)
      .optional()
      .describe("문서 메타데이터 포함 여부 (기본값: false)")
  };

• src/server.ts:78-90 (registration)

  Registers the 'get-document-by-id' tool on the MCP server using server.tool(), providing name, description, input schema, and the handler function.

    server.tool(
      "get-document-by-id",
      `문서 ID로 특정 BaaS 인증 시스템 문서의 전체 내용을 조회합니다.
  
  ⚠️ **중요**: 이 문서만으로 구현하지 말고, \`get-project-config\`에서 제공하는 필수 구현 규칙을 함께 적용해야 합니다.
  
  📌 **필수 참조 사항**:
  - 보안 설정: credentials, HttpOnly 쿠키
  - 에러 처리: ServiceException 표준 형식
  - 상태 관리: 조건부 렌더링 패턴`,
      GetDocumentByIdSchema,
      getDocumentByIdTool.handler
    );

• src/repository/baas-docs.repository.ts:108-112 (helper)

  Core repository method used by the tool handler to retrieve a BaaSDocument by its numeric ID from both feature and common documents.

  getDocumentById(id: number): BaaSDocument | undefined {
    // Feature와 common 문서 모두에서 검색
    const allDocs = [...this.featureDocs, ...this.commonDocs];
    return allDocs.find(doc => doc.getId() === id);
  }