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 등과의 연동을 위해 공식 문서 참조 필수