Back to blog

Protobuf둜 MCP μ„œλ²„ κ΅¬μΆ•ν•˜κΈ° 2λΆ€: protoc ν”ŒλŸ¬κ·ΈμΈμœΌλ‘œ MCP μ„œλ²„ μžλ™ 생성

August 10, 2026

μž‘μ„±μž: EDB Korea Team

2025λ…„ 9μ›” 21일

이 λΈ”λ‘œκ·Έ μ‹œλ¦¬μ¦ˆμ—μ„œλŠ” μœ μš©ν•œ λ„κ΅¬λ“€λ‘œ 가득 μ°¬ MCP (Model Context Protocol) μ„œλ²„λ₯Ό κ΅¬μΆ•ν•˜λŠ” 방법을 λ³΄μ—¬λ“œλ¦½λ‹ˆλ‹€. μ²˜μŒλΆ€ν„° μ‹œμž‘ν•˜λŠ” λŒ€μ‹ , 기쑴의 ν”„λ‘œν† μ½œ 버퍼와 Google의 gRPC νŠΈλžœμŠ€μ½”λ”©μ„ ν™œμš©ν•  κ²ƒμž…λ‹ˆλ‹€. λ§žμΆ€ν˜• protoc (ν”„λ‘œν† μ½œ 버퍼 컴파일러) ν”ŒλŸ¬κ·ΈμΈμ„ μƒμ„±ν•˜μ—¬ MCP μ„œλ²„λ₯Ό μžλ™μœΌλ‘œ 생성할 수 μžˆμŠ΅λ‹ˆλ‹€. 이 ν†΅ν•©λœ μ ‘κ·Ό 방식을 톡해 gRPC μ„œλΉ„μŠ€, OpenAPI 사양, REST API 및 MCP μ„œλ²„λ₯Ό λͺ¨λ‘ λ™μΌν•œ μ†ŒμŠ€μ—μ„œ 생성할 수 μžˆμŠ΅λ‹ˆλ‹€.


이 λΈ”λ‘œκ·Έ μ‹œλ¦¬μ¦ˆλŠ” 4편으둜 κ΅¬μ„±λ˜μ–΄ μžˆμŠ΅λ‹ˆλ‹€


Protobuf 기반 MCP μ„œλ²„ μžλ™ν™” ꡬ성 μš”μ†Œ

이 νŠœν† λ¦¬μ–Όμ„ 마치면 λ‹€μŒμ„ κ°–κ²Œ λ©λ‹ˆλ‹€:

  • proto νŒŒμΌμ—μ„œ MCP μ„œλ²„λ₯Ό μƒμ„±ν•˜λŠ” λ§žμΆ€ν˜• protoc ν”ŒλŸ¬κ·ΈμΈ
  • μ–΄λ–€ λ©”μ„œλ“œκ°€ MCP 도ꡬ가 될지 ν‘œμ‹œν•˜λŠ” λ§žμΆ€ν˜• μ–΄λ…Έν…Œμ΄μ…˜
  • ν•˜λ‚˜μ˜ μ†ŒμŠ€μ—μ„œ gRPC, REST, MCP μ½”λ“œλ₯Ό μƒμ„±ν•˜λŠ” μ™„μ „ν•œ νŒŒμ΄ν”„λΌμΈ
  • AI μ—μ΄μ „νŠΈκ°€ μƒν˜Έμž‘μš©ν•  수 μžˆλŠ” μž‘λ™ν•˜λŠ” MCP μ„œλ²„

이 기사에 μ–ΈκΈ‰λœ λͺ¨λ“  μ½”λ“œλŠ” GitHub μ €μž₯μ†Œ zhangcz828/proto-to-mcp-tutorialμ—μ„œ 찾을 수 μžˆμŠ΅λ‹ˆλ‹€.


μ „μ œ 쑰건

μ‹œμž‘ν•˜κΈ° 전에, 1λΆ€λ₯Ό μ™„λ£Œν–ˆμœΌλ©° λ‹€μŒμ„ κ°–μΆ”κ³  μžˆλŠ”μ§€ ν™•μΈν•˜μ„Έμš”:

  • 1λΆ€μ˜ μ„œμ  νŠœν† λ¦¬μ–Ό ν”„λ‘œμ νŠΈ
  • Go 1.19+ μ„€μΉ˜
  • Protocol Buffer 컴파일러 (protoc) μ„€μΉ˜
  • Python 3.8+ μ„€μΉ˜ (MCP μ„œλ²„ λŸ°νƒ€μž„μš©)
  • npx μ„€μΉ˜

Protobuf ν”ŒλŸ¬κ·ΈμΈμœΌλ‘œ MCP μ„œλ²„λ₯Ό μžλ™ μƒμ„±ν•˜λŠ” 이유

1λΆ€μ—μ„œλŠ” gRPC νŠΈλžœμŠ€μ½”λ”©μ΄ gRPC 및 REST API μ •μ˜λ₯Ό ν†΅ν•©ν•˜λŠ” 데 μ–΄λ–»κ²Œ 도움이 λ˜λŠ”μ§€ λ³΄μ—¬λ“œλ ΈμŠ΅λ‹ˆλ‹€. proto νŒŒμΌμ—μ„œ μžλ™μœΌλ‘œ μƒμ„±λœ κΉ¨λ—ν•˜κ³  λ¬Έμ„œν™”κ°€ 잘 된 HTTP μ—”λ“œν¬μΈνŠΈλ₯Ό κ°–κ²Œ λ˜μ—ˆμ£ . ν•˜μ§€λ§Œ κ³§ μƒˆλ‘œμš΄ λ¬Έμ œμ— μ§λ©΄ν–ˆμŠ΅λ‹ˆλ‹€. Model Context Protocol을 톡해 AI μ‹œμŠ€ν…œμ΄ μ„œλΉ„μŠ€μ™€ μƒν˜Έμž‘μš©ν•˜λ„λ‘ λ§Œλ“€κ³  μ‹Άμ—ˆλ˜ κ²ƒμž…λ‹ˆλ‹€.

MCPλŠ” AI μ• ν”Œλ¦¬μΌ€μ΄μ…˜μ΄ 도ꡬ와 λ¦¬μ†ŒμŠ€μ— ν”„λ‘œκ·Έλž˜λ° λ°©μ‹μœΌλ‘œ μ ‘κ·Όν•˜κΈ° μœ„ν•œ ν‘œμ€€ν™”λœ λ°©λ²•μž…λ‹ˆλ‹€. 우리의 ν†΅ν•©λœ μ ‘κ·Ό 방식이 μ—†μ—ˆλ‹€λ©΄, 각 μ„œλΉ„μŠ€μ— λŒ€ν•΄ μˆ˜λ™μœΌλ‘œ MCP μ„œλ²„ μ½”λ“œλ₯Ό μž‘μ„±ν•΄μ•Ό ν–ˆμ„ κ²ƒμž…λ‹ˆλ‹€. μ΄λŠ” 기본적으둜 gRPC μ„œλΉ„μŠ€, REST μ—”λ“œν¬μΈνŠΈ 및 OpenAPI 사양과 ν•¨κ»˜ μœ μ§€ 관리해야 ν•  λ„€ 번째 API μ •μ˜ μ„ΈνŠΈλ₯Ό λ§Œλ“œλŠ” 것과 κ°™μ•˜μŠ΅λ‹ˆλ‹€.

μ΄λ•Œ μš°λ¦¬λŠ” protoc 기반 μ ‘κ·Ό 방식을 ν™•μž₯ν•  수 μžˆλ‹€λŠ” 것을 κΉ¨λ‹¬μ•˜μŠ΅λ‹ˆλ‹€. proto νŒŒμΌμ—μ„œ REST API와 OpenAPI 사양을 생성할 수 μžˆλ‹€λ©΄, MCP μ„œλ²„λ„ 생성할 수 μžˆμ§€ μ•Šμ„κΉŒμš”? REST μ—”λ“œν¬μΈνŠΈ 생성을 μ•ˆλ‚΄ν–ˆλ˜ λ™μΌν•œ HTTP μ–΄λ…Έν…Œμ΄μ…˜μ΄ MCP 도ꡬλ₯Ό κ΅¬μ‘°ν™”ν•˜λŠ” 방법을 μ•Œλ €μ€„ 수 μžˆμ—ˆμŠ΅λ‹ˆλ‹€.


Protobuf MCP μ„œλ²„ ν”„λ‘œμ νŠΈ μ„€μ •

1λΆ€μ˜ νŠœν† λ¦¬μ–Ό ν”„λ‘œμ νŠΈλ₯Ό ν™•μž₯ν•˜λŠ” 것뢀터 μ‹œμž‘ν•˜κ² μŠ΅λ‹ˆλ‹€. νŠœν† λ¦¬μ–Ό λ””λ ‰ν† λ¦¬λ‘œ λŒμ•„κ°€ λ‹€μŒ λͺ…령을 μ‹€ν–‰ν•˜μ„Έμš”:

cd proto-to-mcp-tutorial
# ν”ŒλŸ¬κ·ΈμΈ 및 MCP μ½”λ“œμš© 디렉토리 생성
mkdir -p plugins/protoc-gen-mcp
mkdir -p generated/mcp
mkdir -p google/protobuf
mkdir -p mcp/protobuf

ν”„λ‘œμ νŠΈ κ΅¬μ‘°λŠ” 이제 MCP κ΄€λ ¨ 디렉토리가 μΆ”κ°€λ˜μ–΄ λ‹€μŒκ³Ό κ°™μ•„μ•Ό ν•©λ‹ˆλ‹€:

proto-to-mcp-tutorial
β”œβ”€β”€ cmd
β”‚   └── server
β”‚       └── main.go
β”œβ”€β”€ generate.sh
β”œβ”€β”€ generated
β”‚   β”œβ”€β”€ go
β”‚   β”‚   β”œβ”€β”€ bookstore_grpc.pb.go
β”‚   β”‚   β”œβ”€β”€ bookstore.pb.go
β”‚   β”‚   └── bookstore.pb.gw.go
β”‚   β”œβ”€β”€ mcp                # New
β”‚   └── openapi
β”‚       └── openapi.yaml
β”œβ”€β”€ go.mod
β”œβ”€β”€ go.sum
β”œβ”€β”€ google
β”‚   └── protobuf          # New
β”œβ”€β”€ mcp                   # New
β”‚   └── protobuf
β”œβ”€β”€ googleapis
β”‚   └── google
β”‚       └── api
β”‚           β”œβ”€β”€ annotations.proto
β”‚           └── http.proto
β”œβ”€β”€ plugins               # New
β”‚   └── protoc-gen-mcp     
β”œβ”€β”€ proto
β”‚   └── bookstore.proto
└── README.md


MCP 도ꡬ 지정을 μœ„ν•œ λ§žμΆ€ν˜• μ–΄λ…Έν…Œμ΄μ…˜ 생성

1. ν•„μˆ˜ proto 파일 λ‹€μš΄λ‘œλ“œ

curl -o google/protobuf/descriptor.proto \
https://raw.githubusercontent.com/protocolbuffers/protobuf/refs/heads/main/src/google/protobuf/descriptor.proto

2. MCP μ–΄λ…Έν…Œμ΄μ…˜ μ •μ˜

μ–΄λ–€ RPC λ©”μ„œλ“œκ°€ MCP 도ꡬ가 λ˜μ–΄μ•Ό ν•˜λŠ”μ§€ ν‘œμ‹œν•˜κΈ° μœ„ν•΄ λ§žμΆ€ν˜• μ–΄λ…Έν…Œμ΄μ…˜μ„ 생성해야 ν•©λ‹ˆλ‹€. μƒˆ 파일 mcp/protobuf/annotations.protoλ₯Ό μƒμ„±ν•©λ‹ˆλ‹€:

syntax = "proto3";

package example.v1;

option go_package = "proto-to-mcp-tutorial/generated/go/mcp;mcp";

import "google/protobuf/descriptor.proto";

// λ©”μ„œλ“œλ₯Ό MCP λ„κ΅¬λ‘œ ν‘œμ‹œν•˜κΈ° μœ„ν•œ 맞좀 ν™•μž₯ (50003은 μ‚¬μš©μž μ§€μ • ν™•μž₯ ν•„λ“œ 번호)
extend google.protobuf.MethodOptions {
 MCPOptions mcp = 50003;
}

message MCPOptions {
 // 이 λ©”μ„œλ“œκ°€ MCP λ„κ΅¬λ‘œ λ…ΈμΆœλ˜μ–΄μ•Ό ν•˜λŠ”μ§€ μ—¬λΆ€
 bool enabled = 1;
}

3. MCP μ–΄λ…Έν…Œμ΄μ…˜μš© Go μ½”λ“œ 생성

export GOOGLEAPIS_DIR=./googleapis
export MCP_DIR=.
protoc -I${GOOGLEAPIS_DIR} -I${MCP_DIR} --go_out=./generated/go --go_opt=paths=source_relative mcp/protobuf/annotations.proto


MCP μ–΄λ…Έν…Œμ΄μ…˜μœΌλ‘œ Bookstore Proto 파일 μ—…λ°μ΄νŠΈ

이제 proto/bookstore.proto νŒŒμΌμ— MCP μ–΄λ…Έν…Œμ΄μ…˜μ„ μΆ”κ°€ν•˜μ—¬ μ–΄λ–€ λ©”μ„œλ“œλ₯Ό MCP λ„κ΅¬λ‘œ ν™œμ„±ν™”ν• μ§€ ν‘œμ‹œν•©λ‹ˆλ‹€.

syntax = "proto3";
package bookstore.v1;
import "google/api/annotations.proto";
import "mcp/protobuf/annotations.proto";

option go_package = "generated/go/bookstore/v1";

service BookstoreService {
  // Get a book by ID
  rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
      get: "/v1/books/{book_id}"
    };
    option (mcp.v1.tool) = {
      enabled: true
    };
  }
  
  // Create a new book
  rpc CreateBook(CreateBookRequest) returns (Book) {
    option (google.api.http) = {
      post: "/v1/books"
      body: "book"
    };
    option (mcp.v1.tool) = {
      enabled: true
    };
  }
}

message Book {
  string book_id = 1;
  string title = 2;
  string author = 3;
  int32 pages = 4;
}

message GetBookRequest {
  // The ID of the book to retrieve
  string book_id = 1;
}

message CreateBookRequest {
  // The book object to create
  Book book = 1;
}

protoc-gen-mcp ν”ŒλŸ¬κ·ΈμΈ ꡬ좕

plugins/protoc-gen-mcp/main.go νŒŒμΌμ— λ§žμΆ€ν˜• protoc ν”ŒλŸ¬κ·ΈμΈ μ½”λ“œλ₯Ό μž‘μ„±ν•©λ‹ˆλ‹€. 이 Go ν”ŒλŸ¬κ·ΈμΈμ€ proto νŒŒμΌμ„ ꡬ문 λΆ„μ„ν•˜κ³ , MCP μ–΄λ…Έν…Œμ΄μ…˜μ„ ν™•μΈν•œ λ‹€μŒ, Python MCP μ„œλ²„ μ½”λ“œλ₯Ό μƒμ„±ν•©λ‹ˆλ‹€.

package main

import (
	"bytes"
	"fmt"
	"regexp"
	"strings"
	"text/template"

	"google.golang.org/protobuf/compiler/protogen"
	"google.golang.org/protobuf/proto"
	"google.golang.org/protobuf/reflect/protoreflect"
	"google.golang.org/protobuf/types/descriptorpb"
	"google.golang.org/protobuf/types/pluginpb"

	mcpannotations "proto-to-mcp-tutorial/generated/go/mcp/protobuf"

	httpannotations "google.golang.org/genproto/googleapis/api/annotations"
)

func main() {
	protogen.Options{}.Run(func(gen *protogen.Plugin) error {
		gen.SupportedFeatures = uint64(pluginpb.CodeGeneratorResponse_FEATURE_PROTO3_OPTIONAL)

		// Extract MCP methods from the proto files
		mcpMethods := extractMCPMethods(gen)

		if len(mcpMethods) == 0 {
			return nil // No MCP methods found
		}

		// Generate main server file
		generateMCPServer(gen, mcpMethods)

		return nil
	})
}

type MCPMethod struct {
	Service     *protogen.Service
	Method      *protogen.Method
	ToolName    string
	Description string
	HTTPInfo    *HTTPInfo
	Input       *protogen.Message
	Output      *protogen.Message
	Parameters  []*MCPParameter
}

type MCPParameter struct {
	Name        string
	Type        string
	Required    bool
	Description string
}

type HTTPInfo struct {
	Method string
	Path   string
	Body   string
}

func extractMCPMethods(gen *protogen.Plugin) []*MCPMethod {
	var mcpMethods []*MCPMethod

	for _, file := range gen.Files {
		if !file.Generate {
			continue
		}

		for _, service := range file.Services {
			for _, method := range service.Methods {
				if hasMCPToolAnnotation(method) {
					mcpMethod := &MCPMethod{
						Service:     service,
						Method:      method,
						ToolName:    generateToolName(method),
						Description: extractDescription(method),
						HTTPInfo:    extractHTTPInfo(method),
						Input:       method.Input,
						Output:      method.Output,
						Parameters:  extractParameters(method.Input),
					}
					mcpMethods = append(mcpMethods, mcpMethod)
				}
			}
		}
	}

	return mcpMethods
}

func hasMCPToolAnnotation(method *protogen.Method) bool {
	options := method.Desc.Options().(*descriptorpb.MethodOptions)
	if options == nil {
		return false
	}

	// Check if method has mcp.v1.tool annotation
	if !proto.HasExtension(options, mcpannotations.E_Tool) {
		return false
	}

	// Get annotation value and check if enabled
	toolOptions := proto.GetExtension(options, mcpannotations.E_Tool).(*mcpannotations.MCPToolOptions)
	return toolOptions != nil && toolOptions.Enabled
}

func extractParameters(inputType *protogen.Message) []*MCPParameter {
	var parameters []*MCPParameter

	if inputType != nil {
		for _, field := range inputType.Fields {
			param := &MCPParameter{
				Name:        string(field.Desc.Name()),
				Type:        getFieldType(field),
				Required:    isFieldRequired(field),
				Description: extractFieldDescription(field),
			}
			parameters = append(parameters, param)
		}
	}

	return parameters
}

func isFieldRequired(field *protogen.Field) bool {
	// In proto3, technically all fields are optional, but for business logic:
	// If the field not marked as optional keyword, consider it required
	if field.Desc.HasOptionalKeyword() {
		return false
	}

	return true
}

func getFieldType(field *protogen.Field) string {
	// Check if the field is repeated (array/list)
	if field.Desc.Cardinality() == protoreflect.Repeated {
		return "list"
	}

	switch field.Desc.Kind() {
	case protoreflect.StringKind:
		return "string"
	case protoreflect.Int32Kind, protoreflect.Int64Kind:
		return "integer"
	case protoreflect.BoolKind:
		return "boolean"
	case protoreflect.MessageKind:
		return "object"
	case protoreflect.EnumKind:
		return "string"
	default:
		return "string"
	}
}

func extractFieldDescription(field *protogen.Field) string {
	if field.Comments.Leading != "" {
		return strings.TrimSpace(string(field.Comments.Leading))
	}
	return ""
}

func generateToolName(method *protogen.Method) string {
	methodName := string(method.Desc.Name())

	// Convert to snake_case
	methodName = camelToSnake(methodName)

	return methodName
}

func camelToSnake(str string) string {
	re := regexp.MustCompile("([a-z0-9])([A-Z])")
	snake := re.ReplaceAllString(str, "${1}_${2}")
	return strings.ToLower(snake)
}

func extractDescription(method *protogen.Method) string {
	if method.Comments.Leading != "" {
		return strings.TrimSpace(string(method.Comments.Leading))
	}
	return fmt.Sprintf("Execute %s RPC method", method.Desc.Name())
}

func extractHTTPInfo(method *protogen.Method) *HTTPInfo {
	options := method.Desc.Options().(*descriptorpb.MethodOptions)
	if options == nil {
		return nil
	}

	if !proto.HasExtension(options, httpannotations.E_Http) {
		return nil
	}

	httpRule := proto.GetExtension(options, httpannotations.E_Http).(*httpannotations.HttpRule)
	if httpRule == nil {
		return nil
	}

	info := &HTTPInfo{}

	switch pattern := httpRule.Pattern.(type) {
	case *httpannotations.HttpRule_Get:
		info.Method = "GET"
		info.Path = pattern.Get
	case *httpannotations.HttpRule_Post:
		info.Method = "POST"
		info.Path = pattern.Post
		info.Body = httpRule.Body
	case *httpannotations.HttpRule_Put:
		info.Method = "PUT"
		info.Path = pattern.Put
		info.Body = httpRule.Body
	case *httpannotations.HttpRule_Delete:
		info.Method = "DELETE"
		info.Path = pattern.Delete
	case *httpannotations.HttpRule_Patch:
		info.Method = "PATCH"
		info.Path = pattern.Patch
		info.Body = httpRule.Body
	}

	return info
}

func generateMCPServer(gen *protogen.Plugin, mcpMethods []*MCPMethod) {
	outputFile := gen.NewGeneratedFile("mcp_server.py", ".")

	funcMap := template.FuncMap{
		"contains": func(s, substr string) bool {
			return strings.Contains(s, substr)
		},
		"printf": fmt.Sprintf,
		"indent": func(text string, spaces int) string {
			if text == "" {
				return text
			}
			lines := strings.Split(text, "\n")
			indentStr := strings.Repeat(" ", spaces)
			var result []string
			for i, line := range lines {
				if strings.TrimSpace(line) != "" {
					result = append(result, indentStr+line)
				} else if i < len(lines)-1 { // Keep empty lines except the last one
					result = append(result, "")
				}
			}
			return strings.Join(result, "\n")
		},
	}

	tmpl := template.Must(template.New("mcp_server").Funcs(funcMap).Parse(mcpServerTemplate))

	var buf bytes.Buffer
	if err := tmpl.Execute(&buf, mcpMethods); err != nil {
		return
	}

	outputFile.P(buf.String())
}

const mcpServerTemplate = `#!/usr/bin/env python3
"""
MCP Server for UPM API - Auto-generated from Protocol Buffers

This server provides access to project management operations
through the Model Context Protocol.
"""

import os
import sys
from typing import Any
import json

import httpx
from mcp.server.fastmcp import FastMCP

API_BASE = 'http://localhost:8080'
VERIFY_SSL = False

# Initialize FastMCP
mcp = FastMCP('Bookstore Server')

async def make_api_request(url: str, method: str = "GET", payload: dict = None) -> dict[str, Any] | None:
    """Make a HTTP request to the specified URL."""

    headers = {
        "Content-Type": "application/json",
    }
    # Use SSL verification based on environment variable
    async with httpx.AsyncClient(verify=VERIFY_SSL) as client:
        try:
            if method.upper() == "GET":
                response = await client.get(url, headers=headers, timeout=30.0)
            elif method.upper() == "PUT":
                response = await client.put(url, headers=headers, json=payload, timeout=30.0)
            elif method.upper() == "POST":
                response = await client.post(url, headers=headers, json=payload, timeout=30.0)
            elif method.upper() == "DELETE":
                response = await client.delete(url, headers=headers, timeout=30.0)
            elif method.upper() == "PATCH":
                response = await client.patch(url, headers=headers, json=payload, timeout=30.0)
            else:
                return {"error": f"Unsupported HTTP method: {method}"}
            
            response.raise_for_status()
            
            # Handle DELETE responses that might be empty
            if method.upper() == "DELETE":
                if response.status_code == 200 or response.status_code == 204:
                    return {"success": True, "message": "Resource deleted successfully"}
                
            # Try to parse JSON, return empty dict if no content
            try:
                return response.json()
            except:
                return {"success": True}
                
        except httpx.HTTPStatusError as e:
            return {"error": f"HTTP {e.response.status_code}: {e.response.text}"}
        except Exception as e:
            return {"error": str(e)}

# MCP Tools

{{range .}}
@mcp.tool()
async def {{.ToolName}}({{range $i, $param := .Parameters}}{{if $i}}, {{end}}{{$param.Name}}: {{if eq $param.Type "string"}}str{{else if eq $param.Type "integer"}}int{{else if eq $param.Type "boolean"}}bool{{else if eq $param.Type "list"}}list{{else}}dict{{end}}{{if not $param.Required}} = None{{end}}{{end}}) -> str:
    """{{.Description}}
    {{if .HTTPInfo}}
    HTTP: {{.HTTPInfo.Method}} {{.HTTPInfo.Path}}{{end}}
    
    Parameters:{{range .Parameters}}
    - {{.Name}} ({{.Type}}{{if not .Required}}, optional{{end}}): {{if contains .Description "\n"}}{{indent .Description 6}}{{else}}{{.Description}}{{end}}{{end}}
    
    Returns:
    - str: JSON formatted response from the API containing the result or error information
    """
    try:
        {{if .HTTPInfo}}
        # Construct the URL
        url = f"{API_BASE}{{.HTTPInfo.Path}}"
        {{$httpInfo := .HTTPInfo}}{{range .Parameters}}{{if and .Required (contains $httpInfo.Path (printf "{%s}" .Name))}}
        url = url.replace("{" + "{{.Name}}" + "}", str({{.Name}})){{end}}{{end}}
        
        # Prepare payload for non-GET requests
        payload = {}
        {{range .Parameters}}{{if and (ne $httpInfo.Method "GET") (ne $httpInfo.Method "DELETE") (not (contains $httpInfo.Path (printf "{%s}" .Name)))}}
        {{if .Required}}payload["{{.Name}}"] = {{.Name}}{{else}}if {{.Name}} is not None:
            payload["{{.Name}}"] = {{.Name}}{{end}}{{end}}{{end}}
        
        # Make the API request
        result = await make_api_request(url, "{{.HTTPInfo.Method}}", payload if payload else None)
        {{else}}
        result = {"error": "No HTTP endpoint defined for this method"}{{end}}
        
        # Return formatted JSON response
        import json
        return json.dumps(result, indent=2)
        
    except Exception as e:
        # Handle any errors that occur during execution
        import json
        error_result = {
            "error": f"Tool execution failed: {str(e)}",
            "tool_name": "{{.ToolName}}",
            "error_type": type(e).__name__
        }
        return json.dumps(error_result, indent=2)

{{end}}
if __name__ == '__main__':
    # Run the MCP server
    mcp.run()
`

ν”ŒλŸ¬κ·ΈμΈ 컴파일

# ν”„λ‘œμ νŠΈ 루트 κ²½λ‘œμ—μ„œ μ‹€ν–‰
go build -o protoc-gen-mcp plugins/protoc-gen-mcp/main.go

gRPCΒ·RESTΒ·OpenAPIΒ·MCP μ½”λ“œ 톡합 생성

generate.sh 슀크립트λ₯Ό μ—…λ°μ΄νŠΈν•˜μ—¬ MCP μ„œλ²„ 생성 단계λ₯Ό ν¬ν•¨ν•©λ‹ˆλ‹€.

#!/bin/bash

export GOOGLEAPIS_DIR=./googleapis
export MCP_DIR=.

echo "Checking for required protoc plugins..."

# Check if protoc-gen-go is available
if ! command -v protoc-gen-go &> /dev/null; then
    echo "❌ protoc-gen-go not found. Installing..."
    go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
    if [ $? -ne 0 ]; then
        echo "⚠️  Failed to install protoc-gen-go. Skipping Go generation."
        exit 1
    fi
fi

# Check if protoc-gen-go-grpc is available  
if ! command -v protoc-gen-go-grpc &> /dev/null; then
    echo "❌ protoc-gen-go-grpc not found. Installing..."
    go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
    if [ $? -ne 0 ]; then
        echo "⚠️  Failed to install protoc-gen-go-grpc. Skipping gRPC generation."
        exit 1
    fi
fi

# Check if protoc-gen-grpc-gateway is available
if ! command -v protoc-gen-grpc-gateway &> /dev/null; then
    echo "❌ protoc-gen-grpc-gateway not found. Installing..."
    go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest
    if [ $? -ne 0 ]; then
        echo "⚠️  Failed to install protoc-gen-grpc-gateway. Skipping Gateway generation."
        exit 1
    fi
fi


echo "πŸ”§ Generating Go gRPC code..."

# Step 1: Generate Go code for MCP annotations
echo "πŸ”§ Generating MCP annotations Go code..."
protoc -I${GOOGLEAPIS_DIR} -I${MCP_DIR} --go_out=./generated/go --go_opt=paths=source_relative mcp/protobuf/annotations.proto

# Step 2: Generate Go gRPC code
protoc -I${GOOGLEAPIS_DIR} -I${MCP_DIR} --proto_path=proto --go_out=./generated/go  --go_opt paths=source_relative --go-grpc_out=./generated/go --go-grpc_opt paths=source_relative bookstore.proto


# Generate gRPC Gateway for REST endpoints
echo "πŸ”§ Generating gRPC Gateway..."
protoc -I${GOOGLEAPIS_DIR} -I${MCP_DIR} --proto_path=proto --grpc-gateway_out=./generated/go --grpc-gateway_opt paths=source_relative bookstore.proto

# Generate OpenAPI specifications
echo "πŸ”§ Generating OpenAPI spec..."
protoc -I${GOOGLEAPIS_DIR} -I${MCP_DIR} -I./proto --openapi_out=./generated/openapi \
      --openapi_opt=fq_schema_naming=true \
      --openapi_opt=version="1.0.0" \
      --openapi_opt=title="Bookstore API" \
      bookstore.proto

# Generate MCP server (always available since we have our custom plugin)
echo "πŸ”§ Generating MCP server..."
protoc -I${GOOGLEAPIS_DIR} -I${MCP_DIR} --proto_path=proto \
      --plugin=protoc-gen-mcp=./protoc-gen-mcp \
      --mcp_out=./generated/mcp \
      bookstore.proto

echo ""
echo "πŸŽ‰ Generation complete!"
echo "πŸ“ Check the ./generated directory for all generated files."

μ—…λ°μ΄νŠΈλœ 생성 슀크립트λ₯Ό μ‹€ν–‰ν•©λ‹ˆλ‹€:

./generate.sh

μ•„λž˜μ™€ 같은 결과값을 λ³Ό 수 μžˆμŠ΅λ‹ˆλ‹€:

Checking for required protoc plugins...
πŸ”§ Generating Go gRPC code...
πŸ”§ Generating MCP annotations Go code...
πŸ”§ Generating gRPC Gateway...
πŸ”§ Generating OpenAPI spec...
πŸ”§ Generating MCP server...

πŸŽ‰ Generation complete!
πŸ“ Check the ./generated directory for all generated files.


μƒμ„±λœ MCP μ„œλ²„ μ‹€ν–‰ 및 ν…ŒμŠ€νŠΈ

1. Go μ„œλ²„ μ‹œμž‘ (터미널 1)

터미널 1μ—μ„œ λ‹€μŒ λͺ…령을 μ‹€ν–‰ν•˜μ—¬ (1λΆ€μ—μ„œ κ΅¬μΆ•ν•œ) Go μ„œλ²„λ₯Ό μ‹œμž‘ν•©λ‹ˆλ‹€. 이 μ„œλ²„λŠ” gRPC μ„œλΉ„μŠ€μ™€ REST κ²Œμ΄νŠΈμ›¨μ΄ 역할을 λͺ¨λ‘ μˆ˜ν–‰ν•©λ‹ˆλ‹€.

2. MCP μ„œλ²„ μ„€μ • 및 μ‹œμž‘ (터미널 2)

uv (Python νŒ¨ν‚€μ§€ κ΄€λ¦¬μž)λ₯Ό μ„€μΉ˜ν•œ ν›„, ν™˜κ²½μ„ μ„€μ •ν•˜κ³  MCP μ„œλ²„λ₯Ό μ‹œμž‘ν•©λ‹ˆλ‹€:

# Create Python virtual environment
uv venv
source .venv/bin/activate

# Install MCP server dependencies
uv pip install fastmcp httpx --native-tls

# Start MCP Inspector
npx @modelcontextprotocol/inspector \
uv \
--directory ./generated/mcp \
run \
mcp_server.py

3. MCP 도ꡬ λͺ©λ‘ ν…ŒμŠ€νŠΈ

μ—΄λ¦° MCP Inspector UI νŽ˜μ΄μ§€μ—μ„œ μ—°κ²°ν•œ λ‹€μŒ λͺ¨λ“  도ꡬλ₯Ό λ‚˜μ—΄ν•˜λ©΄, get_bookκ³Ό create_book 두 κ°€μ§€ 도ꡬ가 ν‘œμ‹œλ˜μ–΄μ•Ό ν•©λ‹ˆλ‹€.

MCP Inspector에 ν‘œμ‹œλœ get_book 및 create_book 도ꡬ λͺ©λ‘

4. 도ꡬ μ‹€ν–‰ ν…ŒμŠ€νŠΈ

get_book 도ꡬλ₯Ό μ„ νƒν•˜κ³ , book_id에 book-1을 μž…λ ₯ν•˜κ³  μ‹€ν–‰ν•©λ‹ˆλ‹€. μ΄λŠ” curl -X GET http://localhost:8080/v1/books/book-1κ³Ό λ™μΌν•œ κ²°κ³Όλ₯Ό λ°˜ν™˜ν•΄μ•Ό ν•©λ‹ˆλ‹€.

MCP Inspectorμ—μ„œ get_book 도ꡬλ₯Ό μ‹€ν–‰ν•œ ν…ŒμŠ€νŠΈ κ²°κ³Ό


Protobuf 기반 MCP μ„œλ²„ μžλ™ 생성 κ²°κ³Ό

이제 ν•˜λ‚˜μ˜ proto 파일이 μ„Έ κ°€μ§€ λ‹€λ₯Έ μΈν„°νŽ˜μ΄μŠ€λ₯Ό μƒμ„±ν•˜λŠ” μ™„μ „ν•œ νŒŒμ΄ν”„λΌμΈμ„ κ°–κ²Œ λ˜μ—ˆμŠ΅λ‹ˆλ‹€:

# Test gRPC interface
grpcurl -plaintext -d '{"book_id": "book-1"}' localhost:9090 bookstore.v1.BookstoreService/GetBook

# Test REST interface 
curl http://localhost:8080/v1/books/book-1

# Test MCP interface (as shown above)

μ„Έ κ°€μ§€ λͺ¨λ‘ λ™μΌν•œ 뢁 데이터λ₯Ό λ°˜ν™˜ν•΄μ•Ό ν•©λ‹ˆλ‹€!

λ™μΌν•œ proto νŒŒμΌμ— 이제 gRPC μ„œλΉ„μŠ€, REST μ—”λ“œν¬μΈνŠΈ, OpenAPI 사양 및 MCP 도ꡬλ₯Ό μƒμ„±ν•˜λŠ” 데 ν•„μš”ν•œ λͺ¨λ“  것이 ν¬ν•¨λ˜μ–΄ μžˆμŠ΅λ‹ˆλ‹€.

ν•˜λ‚˜μ˜ Proto νŒŒμΌμ—μ„œ gRPC REST OpenAPI MCP μΈν„°νŽ˜μ΄μŠ€λ₯Ό μƒμ„±ν•˜λŠ” ꡬ쑰


λ‹€μŒ 단계: Proto μ£Όμ„μœΌλ‘œ AI μƒν˜Έμž‘μš© κ°œμ„ 

μƒμ„±λœ MCP 도ꡬλ₯Ό AI μ—μ΄μ „νŠΈλ‘œ ν…ŒμŠ€νŠΈν•˜κΈ° μ‹œμž‘ν–ˆμ„ λ•Œ, μž‘λ™ν•˜λŠ” λ„κ΅¬λ§ŒμœΌλ‘œλŠ” μΆ©λΆ„ν•˜μ§€ μ•Šλ‹€λŠ” μ€‘μš”ν•œ 사싀을 λΉ λ₯΄κ²Œ κΉ¨λ‹¬μ•˜μŠ΅λ‹ˆλ‹€. AI μ—μ΄μ „νŠΈλŠ” 각 도ꡬ가 무엇을 ν•˜λŠ”μ§€, μ–Έμ œ μ μ ˆν•˜κ²Œ μ‚¬μš©ν•΄μ•Ό ν•˜λŠ”μ§€ μ΄ν•΄ν•˜κΈ° μœ„ν•΄ ν’λΆ€ν•˜κ³  μƒμ„Έν•œ μ„€λͺ…이 ν•„μš”ν•©λ‹ˆλ‹€. 3λΆ€μ—μ„œλŠ” proto 주석이 AI μƒν˜Έμž‘μš©μ„ μ•ˆλ‚΄ν•˜λŠ” μ§€λŠ₯적인 MCP 도ꡬ λ¬Έμ„œκ°€ λ˜λŠ” 방법을 보여쀄 κ²ƒμž…λ‹ˆλ‹€.


Protobuf 기반 MCP μ„œλ²„ μžλ™ 생성 FAQ

protoc ν”ŒλŸ¬κ·ΈμΈμœΌλ‘œ MCP μ„œλ²„λ₯Ό μžλ™ μƒμ„±ν•˜λŠ” μ΄μœ λŠ” λ¬΄μ—‡μΈκ°€μš”?

gRPC μ„œλΉ„μŠ€, REST μ—”λ“œν¬μΈνŠΈ, OpenAPI 사양과 MCP μ„œλ²„λ₯Ό 각각 κ΄€λ¦¬ν•˜λ©΄ API μ •μ˜κ°€ μ€‘λ³΅λ©λ‹ˆλ‹€. λ§žμΆ€ν˜• protoc ν”ŒλŸ¬κ·ΈμΈμ„ μ‚¬μš©ν•˜λ©΄ λ™μΌν•œ proto νŒŒμΌμ„ κΈ°μ€€μœΌλ‘œ MCP μ„œλ²„ μ½”λ“œλ₯Ό 생성해 ν•˜λ‚˜μ˜ μ†ŒμŠ€μ—μ„œ μ—¬λŸ¬ μΈν„°νŽ˜μ΄μŠ€λ₯Ό 관리할 수 μžˆμŠ΅λ‹ˆλ‹€.

μ–΄λ–€ RPC λ©”μ„œλ“œκ°€ MCP λ„κ΅¬λ‘œ μƒμ„±λ˜λ‚˜μš”?

이 νŠœν† λ¦¬μ–Όμ—μ„œλŠ” λ§žμΆ€ν˜• MCP μ–΄λ…Έν…Œμ΄μ…˜μ„ ν™œμ„±ν™”ν•œ RPC λ©”μ„œλ“œλ§Œ MCP λ„κ΅¬λ‘œ μΆ”μΆœν•©λ‹ˆλ‹€. ν”ŒλŸ¬κ·ΈμΈμ€ ν•΄λ‹Ή μ–΄λ…Έν…Œμ΄μ…˜κ³Ό HTTP 정보λ₯Ό 확인해 도ꡬ 이름, λ§€κ°œλ³€μˆ˜, μ„€λͺ…, μš”μ²­ 방식을 κ΅¬μ„±ν•©λ‹ˆλ‹€.

μƒμ„±λœ MCP μ„œλ²„λŠ” REST API와 μ–΄λ–»κ²Œ ν†΅μ‹ ν•˜λ‚˜μš”?

μƒμ„±λœ Python MCP μ„œλ²„λŠ” httpxλ₯Ό μ‚¬μš©ν•΄ proto의 HTTP μ–΄λ…Έν…Œμ΄μ…˜μ—μ„œ 얻은 REST μ—”λ“œν¬μΈνŠΈλ₯Ό ν˜ΈμΆœν•©λ‹ˆλ‹€. GET, POST, PUT, DELETE, PATCH μš”μ²­μ„ μ²˜λ¦¬ν•˜κ³  응닡을 JSON ν˜•μ‹μœΌλ‘œ λ°˜ν™˜ν•©λ‹ˆλ‹€.

이 νŠœν† λ¦¬μ–Όμ„ μ‹€ν–‰ν•˜λ €λ©΄ 무엇이 ν•„μš”ν•œκ°€μš”?

1λΆ€μ˜ μ„œμ  νŠœν† λ¦¬μ–Ό ν”„λ‘œμ νŠΈμ™€ ν•¨κ»˜ Go 1.19 이상, Protocol Buffer 컴파일러(protoc), Python 3.8 이상, npxκ°€ ν•„μš”ν•©λ‹ˆλ‹€. μƒμ„±λœ MCP μ„œλ²„ ν…ŒμŠ€νŠΈ λ‹¨κ³„μ—μ„œλŠ” uv, fastmcp, httpx, MCP Inspectorλ₯Ό μ‚¬μš©ν•©λ‹ˆλ‹€.

MCP μ„œλ²„κ°€ μƒμ„±λ˜μ—ˆλŠ”μ§€ μ–΄λ–»κ²Œ ν™•μΈν•˜λ‚˜μš”?

generate.shλ₯Ό μ‹€ν–‰ν•œ λ’€ MCP Inspectorμ—μ„œ μ„œλ²„μ— μ—°κ²°ν•˜κ³  도ꡬ λͺ©λ‘μ„ ν™•μΈν•©λ‹ˆλ‹€. 이 μ˜ˆμ œμ—μ„œλŠ” get_bookκ³Ό create_book이 ν‘œμ‹œλ˜λ©°, get_book μ‹€ν–‰ κ²°κ³Όλ₯Ό λ™μΌν•œ REST API 호좜 결과와 비ꡐ할 수 μžˆμŠ΅λ‹ˆλ‹€.

메일: salesinquiry@enterprisedb.com

PostgreSQL λ„μž…λΆ€ν„° μš΄μ˜κΉŒμ§€, EDB와 ν•¨κ»˜ν•˜μ„Έμš”

PostgreSQL λ„μž…, 운영, μ„±λŠ₯ μ΅œμ ν™” 및 μ—…κ·Έλ ˆμ΄λ“œμ— λŒ€ν•΄ EDB 전문가와 상담해 λ³΄μ„Έμš”.

λ¬Έμ˜ν•˜κΈ°

Share this