mcpj 사용 설명서

<dependency>
  <groupId>com.wangbyul.mcpj</groupId>
  <artifactId>mcpj</artifactId>
  <version>0.1.0</version>
</dependency>

implementation 'com.wangbyul:mcpj:0.1.0'

import com.wangbyul.mcpj.McpServer;
import com.wangbyul.mcpj.protocol.ToolResult;

public class Main {
    public static void main(String[] args) throws Exception {
        McpServer server = McpServer.named("재고 서버")
                .tool("현재_시각", "서버의 현재 시각을 알려 준다",
                        call -> ToolResult.text(java.time.LocalDateTime.now().toString()))
                .build();

        String url = server.listen(8080);
        System.out.println("떴습니다: " + url);
    }
}

curl -s http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{
        "_meta":{
          "io.modelcontextprotocol/protocolVersion":"2026-07-28",
          "io.modelcontextprotocol/clientCapabilities":{}
        }}}'

import com.wangbyul.mcpj.backend.SimpleBackend;
import com.wangbyul.mcpj.json.Json;
import com.wangbyul.mcpj.protocol.ToolResult;
import com.wangbyul.mcpj.protocol.ToolSpec;

Backend inventory = SimpleBackend.id("inventory")
        .tool(ToolSpec.named("check_stock")
                      .description("상품 코드로 현재 재고 수량을 조회한다. "
                                 + "수량과 창고 위치를 함께 돌려준다.")
                      .parameter("sku", "string", "상품 코드. 예: A-1024", true)
                      .readOnly()
                      .build(),
              call -> {
                  String sku = call.requiredString("sku");
                  return ToolResult.structured(Json.obj(
                          "sku", sku,
                          "quantity", inventoryService.count(sku),
                          "warehouse", inventoryService.location(sku)));
              })
        .build();

ToolSpec.named("check_stock")
        .description("...")
        .parameter("sku", "string", "상품 코드", true)
        .outputSchema(Json.obj(
                "type", "object",
                "properties", Json.obj(
                        "quantity", Json.obj("type", "integer"),
                        "warehouse", Json.obj("type", "string"))))
        .build()

ToolSpec.named("refund")
        .description("주문을 환불한다")
        .parameter("orderId", "string", "주문 번호", true)
        .requireScope("orders:write")
        .build()

SimpleBackend.id("docs")
        .resource("docs:///반품정책.md", "반품 정책", "text/markdown",
                  uri -> policyRepository.latestMarkdown())
        .build()

SimpleBackend.id("orders")
        .resourceTemplate("orders:///{orderId}", "주문 상세", "application/json",
                          uri -> orderRepository.findJson(uri))
        .build()

SimpleBackend.id("review")
        .prompt("코드검토", "우리 팀 규칙에 맞춰 코드를 검토한다",
                arguments -> "다음 코드를 검토해 줘. 우리 규칙은 "
                           + conventions.summary() + " 이다.")
        .build()

.prompt("번역", "문서를 지정한 언어로 옮긴다",
        Collections.singletonList(Json.obj(
                "name", "language",
                "description", "옮길 언어",
                "required", true)),
        arguments -> arguments.get("language") + "로 옮겨 줘")

import com.wangbyul.mcpj.backend.annotation.*;

@Service
public class OrderService {

    @McpTool(description = "주문 번호로 주문 상세를 조회한다", readOnly = true)
    public Map<String, Object> findOrder(
            @McpParam(name = "orderId", description = "주문 번호") String orderId) {
        return repository.findAsMap(orderId);
    }

    @McpResource(uri = "orders:///{orderId}", name = "주문 상세",
                 mimeType = "application/json")
    public String orderDocument(
            @McpParam(name = "orderId", description = "주문 번호") String orderId) {
        return repository.findJson(orderId);
    }

    @McpPrompt(description = "이 주문의 문제를 정리한다")
    public String troubleshoot(
            @McpParam(name = "orderId", description = "주문 번호") String orderId) {
        return "주문 " + orderId + " 에 어떤 문제가 있는지 정리해 줘";
    }
}

Backend orders = AnnotatedBackend.id("orders")
        .expose(orderService)
        .expose(customerService)
        .build();

call -> {
    CallContext ctx = call.context();

    // 누가 불렀나
    String who = ctx.principal();
    if (!ctx.hasScope("orders:write")) {
        return ToolResult.failure("권한이 없습니다");
    }

    for (int i = 0; i < total; i++) {
        // 클라이언트가 포기했으면 그만둔다
        ctx.ensureNotCancelled();

        // 진행 상황을 알린다. 값은 반드시 늘어나야 한다
        ctx.progress(i, (double) total, i + "번째 처리 중");
        ctx.log("info", "처리: " + items.get(i));

        process(items.get(i));
    }
    return ToolResult.text("완료");
}

call -> {
    Object answer = call.context().inputResponses().get("folder");

    if (answer == null) {
        // 아직 답이 없다. 물어본다.
        throw InputRequiredException.elicit("folder",
                "어느 폴더에 저장할까요?",
                Json.obj("type", "object", "properties",
                        Json.obj("folder", Json.obj("type", "string"))),
                Json.obj("단계", "폴더선택"));   // 다음 회차까지 들고 갈 문맥
    }

    // 답이 왔다. 이어서 처리한다.
    String folder = Json.strAt(answer, "content", "folder");
    return ToolResult.text(folder + " 에 저장했습니다");
}

String paymentId = payments.begin(orderId);
throw InputRequiredException.elicitUrl("pay",
        "결제를 마쳐 주세요",
        payments.checkoutUrl(paymentId),
        Json.obj("paymentId", paymentId));   // 다음 회차에 이것으로 대조한다

McpEngine engine = McpEngine.builder()
        .name("보고서 서버")
        .backend(reports)
        .tasks(new TaskManager())   // 이것을 켜야 씁니다
        .build();

call -> {
    // 클라이언트가 이 확장을 선언했을 때만 작업으로 접수할 수 있다
    if (!call.context().supportsTasks()) {
        return generateSynchronously();   // 모르는 클라이언트는 그냥 기다리게 한다
    }

    return call.context().startTask(progress -> {
        for (int i = 0; i < 100; i++) {
            if (progress.isCancelled()) {
                return ToolResult.text("취소되었습니다");
            }
            progress.report(i + "% 처리했습니다");
            processChunk(i);
        }
        return ToolResult.text("보고서를 만들었습니다");
    });
}

// 클라이언트도 이 확장을 선언해야 서버가 작업으로 접수합니다
RequestOptions options = RequestOptions.NONE.capabilities(
        Json.obj(Mcp.CAP_EXTENSIONS, Json.obj(Mcp.EXT_TASKS, Json.obj())));

// 도구를 부르면 작업 핸들이 돌아옵니다
ToolResult accepted = client.callTool("generate_report", Json.obj(), options);
String taskId = Json.asString(accepted.toJson().get("taskId"));

// 끝날 때까지 물어봅니다. 확장 선언은 클라이언트가 알아서 붙입니다
while (true) {
    Map<String, Object> status = client.task(taskId);
    if (Mcp.TASK_COMPLETED.equals(Json.asString(status.get("status")))) {
        System.out.println(status.get("result"));
        break;
    }
    Thread.sleep(1000);
}

// 중단하려면
client.cancelTask(taskId);

// 목록이 바뀌었다 — 무엇이 바뀌었는지 가려서 알린다
engine.refresh();

// 리소스 하나의 내용이 바뀌었다
engine.notifyResourceChanged("docs:///반품정책.md");

McpServer server = McpServer.named("CRM 게이트웨이")
        .exposeOpenApi("https://crm.example.com/openapi.json",
                       "/customers/**", "/orders/**")   // 내보낼 경로만 고른다
        .build();

Backend crm = OpenApiBackend.id("crm")
        .documentUrl("https://crm.example.com/openapi.json")
        .baseUrl("https://crm.example.com")
        .include("/customers/**")
        .exclude("/customers/*/delete")
        .bearerToken(() -> tokenStore.current())
        .timeoutMs(10000)
        .build();

McpServer server = McpServer.named("주문 조회")
        .exposeSql(dataSource,
                SqlQuery.select("find_order",
                                "주문 번호로 주문 한 건을 조회한다")
                        .sql("SELECT id, status, total FROM orders WHERE id = ?")
                        .param("orderId", "string", "주문 번호"))
        .build();

Backend crm = McpBackend.id("crm")
        .endpoint("https://crm.example.com/mcp")
        .bearerToken(() -> tokenStore.current())
        .build();

Backend files = McpBackend.id("files")
        .launch("npx", "-y", "@modelcontextprotocol/server-filesystem", "/데이터")
        .env("LOG_LEVEL", "debug")
        .build();

String url = server.listen(8080);   // http://127.0.0.1:8080/mcp

server.listenOnStdio();   // 입력이 끝날 때까지 돌아오지 않습니다

import com.wangbyul.mcpj.transport.servlet.jakarta.McpServlet;

// Tomcat 10+ · Jetty 11+ (jakarta.servlet)
// 서블릿은 McpServer 가 아니라 그 안의 endpoint 를 받습니다.
context.addServlet("mcp", new McpServlet(server.endpoint()))
       .addMapping("/mcp");

// Tomcat 9 이하 (javax.servlet) 라면 패키지만 다릅니다
//   com.wangbyul.mcpj.transport.servlet.McpServlet

McpResponse response = server.handle(
        McpRequest.post()
                .headers(요청헤더)
                .body(요청본문)
                .build());

if (response.isStream()) {
    response.writeStreamTo(출력스트림);   // 스트림이 끝날 때까지 돌아오지 않습니다
} else {
    쓰기(response.status(), response.headers(), response.body());
}

<dependency>
  <groupId>com.wangbyul.mcpj</groupId>
  <artifactId>mcpj-spring-boot-starter</artifactId>
  <version>0.1.0</version>
</dependency>

mcpj:
  name: 주문 서비스
  path: /mcp
  instructions: 주문과 배송을 조회할 수 있습니다
  oauth:
    issuer: https://auth.example.com/realms/main
    resource: https://api.example.com/mcp
  required-scopes: [ orders:read ]

McpServer server = McpServer.named("주문 서비스")
        .expose(orderService)
        .oauth("https://auth.example.com/realms/main",   // 인가 서버
               "https://api.example.com/mcp")             // 이 서버의 주소
        .requireScope("orders:read")
        .build();

McpEngine engine = McpEngine.builder()
        .name("주문 서비스")
        .backend(orders)

        // 누가 무엇을 언제 불렀는지 남긴다
        .auditLog(AuditLog.TO_JAVA_LOGGING)

        // 사용자별로 1분에 60번까지
        .rateLimiter(RateLimiter.perPrincipal(60, 60000))

        // 도구가 많으면 목록을 나눠 준다
        .pageSize(50)

        // 클라이언트에게 알릴 캐시 유효 기간
        .listCacheTtl(60000)

        // backend 오류 내용을 그대로 내보낼지 (기본 꺼짐)
        .exposeBackendErrors(false)
        .build();

List<String> conflicts = engine.resourceConflicts();
if (!conflicts.isEmpty()) {
    health.degraded("리소스가 겹쳐 일부가 빠졌습니다", conflicts);
}

McpClient client = McpClient.connect("https://api.example.com/mcp")
        .bearerToken(() -> tokenStore.current())
        .identifyAs("우리 앱", "1.0")
        .build();

for (ToolSpec tool : client.tools()) {
    System.out.println(tool.name() + " — " + tool.description());
}

ToolResult result = client.callTool("check_stock", Json.obj("sku", "A-1024"));
System.out.println(result.text());

client.close();

McpClient client = McpClient.launch(
                "npx", "-y", "@modelcontextprotocol/server-filesystem", "/데이터")
        .env("LOG_LEVEL", "debug")
        .build();

// close() 하면 띄운 프로그램도 함께 정리됩니다

Subscription listening = client.listen()
        .toolsListChanged()
        .resourcesListChanged()
        .resource("docs:///반품정책.md")      // 이 문서의 내용이 바뀌면
        .start((method, params) -> {
            if (Mcp.N_TOOLS_LIST_CHANGED.equals(method)) {
                try {
                    cachedTools = client.tools();
                } catch (IOException failed) {
                    // 소식은 별도 스레드에서 옵니다. 여기서 던지면 아무도 받지
                    // 못하므로 이 자리에서 처리해야 합니다. 구독은 그대로 살아 있습니다.
                    System.err.println("목록을 다시 받아 오지 못했습니다: " + failed);
                }
            }
        });

// 서버가 무엇을 받아 주기로 했는지 확인할 수 있습니다
Map<String, Object> honored = listening.acknowledgement(5000);

listening.close();