Serve7 MCP Connector Library

Amazon Connect AI Agents와 Bedrock AgentCore를 위한 재사용 가능한 MCP 도구 모음입니다. 고객 조회, 지원 티켓 생성, 티켓 상태 확인, 약속 예약, CRM 레코드 업데이트, 지식 검색, 태스크 생성 — 이 일곱 가지 범용 커넥터를 한 번만 만들어 두면, 프로젝트마다 처음부터 연결하는 대신 모든 Serve7 고객 상호작용에 재사용할 수 있습니다.

이 프로젝트는 Fall 2026 co-op 아이디어 목록의 프로젝트 #6("Serve7 MCP Connector Library")입니다. 현재 동작하는 첫 번째 버전으로, 모든 커넥터가 오늘도 인메모리 mock 백엔드를 대상으로 엔드투엔드로 실행되며, AWS 계정이나 실제 CRM, 자격 증명 없이도 시도해 볼 수 있습니다. 또한 나중에 실제 백엔드로 갈아 끼울 수 있는 깔끔한 결합부(seam)를 갖추고 있습니다.

직접 통합이 아닌 어댑터를 사용하는 이유

각 커넥터의 비즈니스 로직(스키마 검증, 무엇이 오류로 간주되는지, 어떤 필드가 들어오고 나가는지)은 src/connectors/*.ts에 있으며 특정 백엔드 SDK를 직접 사용하지 않습니다. 그 대신 src/adapters/types.ts에 정의된 다섯 가지 작은 인터페이스 중 하나를 호출합니다 — CrmAdapter, TicketingAdapter, SchedulingAdapter, KnowledgeAdapter, TaskAdapter. 현재 이들은 모두 인메모리로 구현되어 있습니다(src/adapters/mock.ts). 나중에 실제 Salesforce/ServiceNow/Connect-Cases/Bedrock-Knowledge-Base 백엔드로 연결하려면 새 어댑터 클래스 하나를 작성하고 스위치 문 하나만 전환하면 됩니다(src/adapters/index.ts) — 커넥터 코드, 해당 테스트, 에이전트가 보는 MCP 도구 정의는 전혀 변경하지 않아도 됩니다. docs/adding-a-real-adapter.md를 참조하세요.

MCP client (Claude Desktop, Bedrock AgentCore, ...)
        │  tool call: customer_lookup({ customerId: "cust-1001" })
        ▼
src/server.ts (stdio) or src/http-server.ts (deployed)
        │  registers every connector as an MCP tool
        ▼
src/connectors/customer-lookup.ts
        │  validates input (zod), calls adapters.crm.lookupCustomer(...)
        ▼
src/adapters/index.ts  →  mock.ts today, a real adapter later

Related MCP server: Runtime MCP Server

프로젝트 구조

src/
  connectors/       one file per MCP tool — schema + business logic only
  adapters/          the CRM/ticketing/scheduling/knowledge/task interfaces,
                      plus the in-memory mock implementations
  mock-data/         seed data the mock adapters serve
  mcp-server-factory.ts   registers every connector on an McpServer instance
  server.ts          stdio entrypoint (local dev, Claude Desktop, Claude Code)
  http-server.ts      Streamable-HTTP entrypoint (deployed, e.g. behind Lambda)
tests/               one test file per connector + a registry sanity test
deploy/              Dockerfile + AWS SAM template for a Lambda deployment
docs/                per-connector reference + how to add a real adapter

로컬에서 실행하기

npm install
npm test              # 29 tests, all against the mock adapters
npm run typecheck      # strict TypeScript, zero `any` in connector code
npm start              # stdio MCP server — Ctrl+C to stop
npm run start:http      # HTTP MCP server on :8080 (curl http://localhost:8080/health)
npm run smoke           # real MCP client over stdio, calls all 7 tools end to end
npm run smoke:http      # same, over HTTP — start:http must be running first

Claude Desktop / Claude Code에 연결하기

MCP 클라이언트를 stdio 서버에 연결하세요. 예를 들어 Claude Desktop의 claude_desktop_config.json에서:

{
  "mcpServers": {
    "serve7-connectors": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/serve7-mcp-connectors/src/server.ts"]
    }
  }
}

그런 다음 "고객 cust-1001 조회" 또는 "비상 마감 안내에 대한 기술 문서는 무엇이 있나요?"처럼 질문해 보세요. 이어 mock 데이터를 대상으로 customer_lookup / retrieve_knowledge를 호출합니다.

실제 사용 배포(예: Bedrock AgentCore에서 시작)

deploy/README.md를 참조하세요. sam deploy로 IAM 인증 방식의 Function URL 뒤에 컨테이너 이미지 Lambda를 빌드합니다.

8번째 커넥터 추가하기

1. 기존 커넥터(예: create-task.ts)의 형태를 사용해서 defineConnector()로 src/connectors/my-new-tool.ts를 만듭니다.

2. src/connectors/index.ts의 CONNECTORS 배열에 추가합니다.

3. tests/에 테스트 파일을 추가합니다.

4. docs/connectors.md에 문서로 기록합니다.

server.ts, http-server.ts, 레지스트리 테스트가 모두 자동으로 처리합니다. 다른 것은 건드릴 필요가 없습니다.

이 첫 번째 버전에서 의도적으로 범위 밖으로 둔 부분

원래 프로젝트 지침에 따라 각 커넥터는 인증 방식(완료 — 어댑터 계층), 배포 템플릿(완료 — deploy/), 문서(완료 — docs/)를 포함해야 하며, 모두 제공되었습니다. 아직 만들지 않았고 빠른 후속 작업이 필요한 것은 하나 이상의 백엔드를 위한 실제 어댑터(그래서 전체가 mock이 되지 않는 것)와 배포된 HTTP 엔드포인트를 통해 실제 동작하는 Bedrock AgentCore 에이전트가 그것을 엔드투엔드로 호출하도록 연결하는 작업입니다.