MCP-ALBERTO

MCP-ALBERTO: AI를 위한 기본 도구 서버

이 프로젝트는 AI 어시스턴트의 기능을 확장하도록 설계된 MCP(Model Context Protocol) 서버를 구현합니다. TotalCheck는 단독으로는 유용성이 제한적일 수 있지만 AI 모델에서 결합 및 조정하여 복잡한 워크플로를 실행하고 특정 외부 서비스(현재는 TotalCheck와 관련된 "ALBERTO"라는 시스템)와 상호 작용하도록 설계된 기본적이고 원자적인 도구 세트를 제공합니다.

목표는 복잡한 사전 패키지 도구를 제공하는 것이 아니라 AI가 자격 증명 획득, 인증, 기본 서비스의 다른 엔드포인트와의 잠재적 상호 작용 등의 작업을 해결하는 데 동적으로 사용할 수 있는 빌딩 블록(기본)을 제공하는 것입니다.

실행 구성(통합 예시)

다음 구성(예)은 이 MCP가 이를 사용하는 도구와 어떻게 통합될 수 있는지 보여줍니다.

지엑스피1

프로젝트 구조

• main.ts : 애플리케이션 진입점. MCP 서버를 초기화하고, 전송(현재 StdioServerTransport )을 구성하고, 사용 가능한 도구를 등록합니다.
• userservice/ :
  • userservice-api-rest.ts : 사용자 서비스 REST API와 상호작용하는 로직을 담고 있습니다(예: 인증 티켓 받기).
  • userservice-tool.ts : 사용자 서비스와 관련된 MCP 도구(예: get_ticket )를 정의하고 등록합니다.
• README.md : 이 파일.
• .gitignore : Git에서 무시되는 파일과 디렉토리를 지정합니다.
• package.json / package-lock.json : Node.js 프로젝트 종속성 관리.
• tsconfig.json : TypeScript 컴파일러 구성.

사용 가능한 MCP 도구

이 서버는 다음과 같은 도구를 제공합니다. 이러한 도구는 저수준의 구성 요소라는 점을 이해하는 것이 중요합니다. AI가 더 큰 목표를 달성하기 위해 이러한 기술을 순차적으로 또는 조합하여 사용할 때 기술의 진정한 잠재력이 발휘됩니다.

• get_node_info
  • 설명: 시스템의 특정 노드에 대한 자세하고 완전한 정보를 얻습니다.
  • 구현: nodeservice/nodeservice-tool.ts
  • 매개변수: unique_id (문자열, 필수 ), alf_ticket (문자열).
  • 사용: 노드의 정확한 unique_id 알려져 있고 모든 세부 정보가 필요할 때 이상적입니다.
• search_by_type
  • 설명: ElasticSearch에서 테넌트 및 유형별 로 유연한 검색을 수행하여 다양한 기준에 따라 노드를 찾을 수 있습니다.
  • 구현: searchservice/by_type/tool.ts
  • 엔드포인트 API: /searchservice/tenant/{tenant}/type/{type}/...
  • 매개변수:
    • tenant_name (문자열, 필수 ): 검색할 테넌트입니다.
    • type_name (문자열, 필수 ): 쿼리할 특정 인덱스/유형(예: expediente_inscripcion_mt ).
    • query_body (문자열, 필수 ): JSON 문자열 형식의 ElasticSearch 쿼리입니다.
    • alf_ticket (문자열): 인증 티켓.
    • from_index (숫자, 선택 사항): 페이지 번호 매기기.
    • page_size (숫자, 선택 사항): 페이지 번호 매기기.
    • sort (문자열, 선택 사항): 정렬.
  • 용도: 특정 인덱스(파일, 사용자 등)를 대상으로 검색하는 경우.
• search_workflow
  • 설명: ElasticSearch의 Workflow taskmanager 별칭에 대한 유연한 검색을 수행합니다.
  • 구현: searchservice/workflow/tool.ts
  • 엔드포인트 API: /searchservice/workflow/...
  • 매개변수:
    • query_body (문자열, 필수 ): JSON 문자열 형식의 ElasticSearch 쿼리입니다.
    • alf_ticket (문자열): 인증 티켓.
    • from_index (숫자, 선택 사항): 페이지 번호 매기기.
    • page_size (숫자, 선택 사항): 페이지 번호 매기기.
  • 용도: 작업이나 워크플로 정보를 찾는데, 일부 데이터만 사용 가능한 경우(특허, 운영) 사례의 unique_id 나 type_name 알아내기 위한 중간 단계로 유용합니다.
• get_ticket
  • 설명: 외부 로그인 서비스에서 인증 티켓을 가져옵니다.
  • 구현: userservice/userservice-tool.ts
  • 매개변수:
    • usuario (문자열): 인증을 위한 사용자 이름입니다.
    • password (문자열): 사용자 비밀번호.
  • 반환값: 인증 티켓을 텍스트로 반환합니다.
• get_config_credentials
  • 설명: 구성 자격 증명(사용자, 키, 설명)의 미리 정의된 목록을 가져옵니다.
  • 구현: configuraciones/configuraciones-tool.ts
  • 매개변수: 없음.
  • 반환값: username , clave , description 포함하는 JSON 객체의 배열입니다.
  • 참고: AI에게 시스템과 상호 작용하는 데 사용할 수 있는 ID를 제공하세요.

일반적인 워크플로

• 구성 자격 증명으로 티켓 받기:
  1. get_config_credentials 호출하여 미리 구성된 사용자 이름과 비밀번호를 가져옵니다.
  2. JSON 결과에서 usuario 과 password 추출합니다.
  3. 이전 단계에서 얻은 usuario 과 password 전달하여 get_ticket 호출합니다.

AI 오케스트레이션(개념적 예)

AI 비서는 "관리자 사용자를 위한 티켓을 받으세요"와 같은 요청을 받을 수 있습니다. AI는 사용 가능한 도구를 사용하여 다음 단계를 수행합니다.

1. get_config_credentials 호출합니다 . 사용자 목록과 설명을 가져옵니다.
2. 사용자 식별 : 응답을 처리하여 "관리자 사용자" 설명에 해당하는 username 찾습니다.
3. get_ticket 호출 : 식별된 username 과 clave (암시적 또는 추출된)를 사용하여 인증 티켓을 요청합니다.
4. 현재 결과 : 획득한 티켓을 사용자에게 반환합니다.

이 예는 AI의 지시에 따라 간단한 도구가 어떻게 결합되어 복잡한 요구 사항을 충족하는지 보여줍니다.

서비스와 Elasticsearch 간의 상호 작용

search_by_type , search_workflow 및 get_node_info 가 어떻게 상호 작용하는지, 그리고 이들이 Elasticsearch의 데이터 구조와 어떻게 관련되어 있는지 이해하는 것이 중요합니다.

1. 기본 인덱스: 각 기본 엔터티 유형(예: expediente_inscripcion_mt , expediente_operacion_leasing , user , tenant )은 자체 ElasticSearch 인덱스에 있습니다. search_by_type 적절한 type_name 지정하여 이러한 인덱스를 직접 쿼리할 수 있습니다.
2. 워크플로 인덱스( taskmanager_* ): 노드가 워크플로에 들어가면 워크플로별 인덱스(예: taskmanager_expediente_inscripcion_mt )에 항목이 생성됩니다.
3. 별칭 taskmanager : 모든 워크플로 인덱스를 그룹화하는 taskmanager 라는 별칭이 있습니다. search_workflow 나 search_by_type 사용하면 모든 활성 작업을 검색할 수 있습니다.
4. 일반적인 흐름:
   • 기본 유형이 알려져 있는 경우 AI는 search_by_type 직접 사용합니다.
   • 일반 정보를 찾고 있거나 정확한 유형을 알 수 없는 경우 AI는 search_workflow (별칭 taskmanager 쿼리)를 검색 단계로 사용할 수 있습니다.
   • search_workflow 또는 search_by_type 의 결과에는 필요한 정보나 부모 노드의 unique_id 포함될 수 있습니다.
   • unique_id 얻고 모든 세부 정보가 필요한 경우 AI는 get_node_info 사용할 수 있습니다.

AI 가이드: 최소 검색 조건

관련성 있고 효율적인 결과를 보장하기 위해, search_by_type 또는 search_workflow 에 대한 query_body 구성할 때 AI는 사용자 요청에서 명시적으로 달리 명시하지 않는 한 다음과 같은 최소 기본 조건을 적용해야 합니다.

• 기본 인덱스(예: expediente_* , user , tenant )를 쿼리할 때:
  • 삭제된 레코드를 제외합니다. 쿼리에 포함:
    { "query": { "bool": { "must_not": [{ "term": { "deleted": true } }] } } }
    (다른 must 와 결합하고, bool 내에서 필요에 따라 절을 filter .)
• Alias taskmanager 쿼리할 때:
  • 활성 작업만 포함하고 삭제된 레코드는 제외합니다.
  • 쿼리에 포함:
    { "query": { "bool": { "must": [{ "term": { "status": "active" } }], "must_not": [{ "term": { "deleted": true } }] } } }
    (실제 이름이 다른 경우 status 필드와 active 값을 조정합니다. 다른 must , filter 절과 결합합니다.)

주요 기술 세부 사항

1- package.json 의 추가 구성 - "type": "module" : ES6 모듈(가져오기/내보내기)을 사용할 수 있습니다.

2- 중요 패키지( dependencies ) - @modelcontextprotocol/sdk : MCP 서버를 생성하는 SDK입니다. - zod : 스키마 검증(도구 정의에 사용)에 사용됩니다. - axios : REST API를 호출하기 위한 HTTP 클라이언트. - tsx : TypeScript 파일을 직접 실행합니다.

3- MCP 메인 파일 - main.ts : 메인 오케스트레이터. - userservice/userservice-api-rest.ts : API 호출 로직. - userservice/userservice-tool.ts : MCP 도구의 정의.

지역 개발을 위한 명령

1. 종속성 설치:
   npm install
2. MCP 서버를 실행합니다.
   npx tsx main.ts
   서버가 시작되고 stdio를 통한 통신을 기다립니다.