How to Create an MCP Server with Symfony

Symfony로 MCP 서버를 생성하는 방법

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

웹 개발

대상자

  • Symfony 프레임워크 및 AI 도구 연동 개발자
  • MCP 프로토콜 구현에 관심 있는 중급 이상 개발자
  • LLM(Large Language Model)과 외부 도구 연동을 위한 API 설계자

핵심 요약

  • MCP(Model Context Protocol)는 LLM(Large Language Model)이 외부 도구(Tool)와 상호작용하는 JSON-RPC 기반 프로토콜로, initialize, tools/list, tools/call 3가지 메서드를 지원
  • Symfony에서 MCP 서버 구현은 ecourty/mcp-server-bundle을 사용해 JSON-RPC 핸들링과 툴 등록을 자동화
  • AsTool 어트리뷰트를 사용해 클래스를 MCP 툴로 등록, __invoke 메서드를 통해 입력값 처리 및 ToolResult 반환

섹션별 세부 요약

1. MCP 프로토콜 개요

  • LLM이 외부 도구와 연동할 수 있도록 하는 JSON-RPC 기반 프로토콜
  • tools/list 메서드로 서버의 사용 가능한 툴 목록 반환
  • tools/call 메서드로 툴 이름과 인자 전달해 실행
  • MCP 서버는 HTTP 통신을 사용하며, 클라이언트와의 버전/능력 교환initialize 메서드로 처리

2. Symfony에서 MCP 서버 구축

  • ecourty/mcp-server-bundle 설치 명령:

```bash

composer require ecourty/mcp-server-bundle

```

  • bundles.php 파일에 블랜드 추가 (Symfony Flex 미사용 시)

```php

Ecourty\McpServerBundle\McpServerBundle::class => ['all' => true],

```

  • mcp.yaml 라우팅 설정:

```yaml

mcp_controller:

path: /mcp

controller: mcp_server.entrypoint_controller

```

3. 툴 구현 방법

  • AsTool 어트리뷰트를 사용해 클래스를 툴로 등록

```php

use Ecourty\McpServerBundle\Attribute\AsTool;

#[AsTool(name: 'get_url_content', description: 'Retrieves the content of a URL')]

class RetrieveURLContentTool

```

  • __invoke 메서드 구현:

```php

public function __invoke(RetrieveURLContent $payload): ToolResult

{

$url = $payload->url;

$content = file_get_contents($url);

return new ToolResult([...]);

}

```

  • 입력 스키마 정의: OpenAPI 어트리뷰트 사용

```php

use OpenApi\Attributes as OA;

class RetrieveURLContent

{

#[OA\Property(type: 'string', format: 'uri')]

public string $url;

}

```

4. 툴 검증 및 디버깅

  • bin/console debug:mcp-tools 명령으로 등록된 툴 확인
  • tools/list JSON-RPC 요청 시 다음과 같은 응답 반환:

```json

{

"tools": [

{

"name": "get_url_content",

"description": "Retrieves the content of a URL",

"inputSchema": {

"type": "object",

"properties": {

"url": { "type": "string", "format": "uri" }

}

}

}

]

}

```

5. 추가 기능 및 확장성

  • 이벤트 리스닝, 커스텀 JSON-RPC 메서드 처리, 커스텀 툴 결과 생성 지원
  • Visual Studio Code, JetBrains IDE, n8n과의 연동을 위한 문서 참고

결론

  • MCP 서버 구축 시 ecourty/mcp-server-bundle 사용해 JSON-RPC 핸들링과 툴 등록을 간소화
  • AsTool 어트리뷰트와 __invoke 메서드를 통해 툴 생성, 입력 스키마 정의 시 OpenAPI 어트리뷰트 사용
  • bin/console debug:mcp-tools 명령으로 툴 등록 여부 확인 후, tools/list JSON-RPC 요청으로 클라이언트에서 사용 가능
  • Visual Studio Code, JetBrains IDE 등과의 연동을 위해 공식 문서 참조 필수