[Feat] MCP 서버 골격 및 도구 3종 스켈레톤 등록 by kangcheolung · Pull Request #95 · DocGrid/backend

kangcheolung · 2026-08-05T07:03:44Z

배경

DocGrid의 검색/문서조회/인덱싱상태 조회 기능을 MCP 표준(JSON-RPC 2.0, Streamable HTTP)으로 노출해
Claude Desktop 같은 AI Agent가 직접 호출할 수 있게 하는 MCP Server 블록의 첫 번째 이슈입니다.
Spring AI MCP SDK 연동이 이 프로젝트에서 처음 시도되는 것이라, 실제 검색/권한 로직을 붙이기 전에
어노테이션 스캔 기반 도구 등록이 정상 동작하는지부터 검증할 필요가 있었습니다.

변경 사항

spring-ai-bom:1.1.8 + spring-ai-starter-mcp-server-webmvc 의존성을 추가하고 Streamable HTTP(protocol=STREAMABLE, type=SYNC)로 설정했습니다.
@McpTool/@McpToolParam 어노테이션으로 search_documents/get_document_detail/get_indexing_status 빈 핸들러 3개를 등록했습니다 (실제 로직은 후속 이슈).
/mcp/**를 임시로 permitAll 처리했습니다 (다음 이슈에서 API 키 인증 필터로 교체 예정, TODO 명시).
설계 문서에 SDK 내부 구조(패키지 경로, 설정 프로퍼티, 알려진 SDK 버그 회피 근거)와 실제 tools/list 검증 결과를 기록했습니다.

검증

./gradlew compileJava 정상 컴파일
로컬 기동 후 curl로 JSON-RPC initialize → tools/list 흐름을 직접 호출해 도구 3종의 name/description/inputSchema(필수값 포함)가 정상 반환되는 것을 확인했습니다.
애플리케이션 로그에서 Registered tools: 3 확인.

문서

docs/design/kangcheolung-#93-mcp-server-skeleton.md

Closes #93

Summary by CodeRabbit

새 기능
- MCP 서버 기반을 추가했습니다.
- 문서 검색, 문서 상세 조회, 인덱싱 상태 확인을 위한 세 가지 도구를 제공합니다.
- 스트리밍 및 동기식 통신을 지원하며 도구 목록과 입력 형식을 자동으로 제공합니다.
문서
- MCP 서버 설정과 사용 가능한 도구, 초기화 및 도구 목록 확인 절차를 문서화했습니다.
제한 사항
- 현재 각 도구는 실제 검색·조회·인덱싱 로직과 연결되지 않았으며, 인증은 후속 작업으로 예정되어 있습니다.

spring-ai-bom 1.1.8 기반 spring-ai-starter-mcp-server-webmvc를 도입하고 protocol=STREAMABLE, annotation-scanner.enabled=true로 설정한다.

@McpTool/@McpToolParam 어노테이션 스캔이 정상 동작하는지 검증하기 위해 search_documents, get_document_detail, get_indexing_status 빈 핸들러를 등록한다. 실제 로직은 후속 이슈에서 구현한다.

/mcp/** 를 임시로 permitAll 처리한다. API 키 인증 필터(McpApiKeyAuthFilter)는 다음 이슈에서 구현 후 이 예외를 교체한다.

Spring AI 1.1.x 채택 근거, javap로 검증한 SDK 내부 구조(패키지 경로, 설정 프로퍼티, #4882/#4392 회피 경로), tools/list 실제 검증 결과를 기록한다.

coderabbitai · 2026-08-05T07:04:07Z

Warning

Review limit reached

@kangcheolung, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 46 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 1f3e24bd-f399-4c9a-a7fc-8bfe8a6fc997

📥 Commits

Reviewing files that changed from the base of the PR and between a1ec53e and b41887b.

📒 Files selected for processing (3)

docs/design/kangcheolung-#93-mcp-server-skeleton.md
src/main/java/com/opensource/docgrid/domain/mcp/tool/DocGridMcpTools.java
src/main/resources/application.yml

📝 Walkthrough

Walkthrough

Spring AI MCP WebMVC Starter를 추가했다. Streamable 동기식 MCP 서버를 설정했다. 세 개의 빈 도구를 등록했다. /mcp/** 경로를 임시로 인증 예외 처리했다. JSON-RPC 도구 목록 검증 결과를 문서화했다.

Changes

MCP 서버 스켈레톤

Layer / File(s)	Summary
MCP 의존성 및 적용 범위 `build.gradle`, `docs/design/...mcp-server-skeleton.md`	Spring AI BOM 1.1.8과 MCP WebMVC Starter를 추가했다. Spring Boot 및 Java 호환성과 SDK 검증 내용을 문서화했다.
MCP 서버 및 도구 연결 `application.yml`, `src/main/java/com/opensource/docgrid/domain/mcp/tool/DocGridMcpTools.java`, `src/main/java/com/opensource/docgrid/global/config/SecurityConfig.java`, `docs/design/...mcp-server-skeleton.md`	`STREAMABLE`·`SYNC` 서버와 annotation scanner를 설정했다. `search_documents`, `get_document_detail`, `get_indexing_status` 도구를 등록했다. `/mcp/**` 접근을 `permitAll()`로 설정했다.
MCP 메타데이터 검증 및 후속 항목 `docs/design/...mcp-server-skeleton.md`	`initialize`와 `tools/list` 결과를 기록했다. 세 도구의 자동 스키마 생성을 확인하고 미구현 오류와 후속 인증 작업을 정리했다.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant MCPClient
  participant MCPWebMVCEndpoint
  participant AnnotationScanner
  participant DocGridMcpTools
  MCPClient->>MCPWebMVCEndpoint: initialize 요청
  MCPWebMVCEndpoint->>AnnotationScanner: `@McpTool` 스캔
  AnnotationScanner->>DocGridMcpTools: 세 도구 등록
  MCPClient->>MCPWebMVCEndpoint: tools/list 요청
  MCPWebMVCEndpoint-->>MCPClient: 세 도구와 입력 스키마 반환

Suggested reviewers: gimini-3

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	제목은 MCP 서버 골격과 세 도구 스켈레톤 등록이라는 주요 변경 사항을 명확하게 요약합니다.
Description check	✅ Passed	변경 내용과 검증 결과, 문서, 연결 이슈를 포함해 템플릿의 핵심 정보를 대부분 충족합니다.
Linked Issues check	✅ Passed	의존성, Streamable HTTP 설정, 세 도구 등록, 임시 인증 예외, tools/list 검증을 모두 구현했습니다 [`#93`].
Out of Scope Changes check	✅ Passed	변경 사항은 MCP 서버 골격 구성, 도구 스켈레톤, 보안 예외, 설계 문서 범위에 포함됩니다.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches 💡 1

⚔️ Resolve merge conflicts 💡

Resolve merge conflict in branch feature/93

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feature/93

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

# Conflicts: # src/main/resources/application.yml

coderabbitai

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/design/kangcheolung-`#93-mcp-server-skeleton.md:
- Line 171: Remove the `// get_document_detail, get_indexing_status 도 동일하게 정상
반환됨` comment from the JSON example near the MCP server response documentation,
and move the omitted-fields explanation outside the JSON code block so the
example remains valid JSON.

In `@src/main/java/com/opensource/docgrid/domain/mcp/tool/DocGridMcpTools.java`:
- Around line 7-8: DocGridMcpTools 클래스에 클래스 수준 Javadoc을 추가하여 MCP 프로토콜의 입력·출력 경계만
담당하고 검색, 권한, 문서 조회 규칙은 도메인 서비스에 위임한다는 역할과 책임 범위를 명시하세요.
- Around line 10-34: Update the `@McpTool` annotations on searchDocuments,
getDocumentDetail, and getIndexingStatus to explicitly set readOnlyHint = true
and destructiveHint = false. Do not alter their authentication or authorization
behavior.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 40fb674b-a74a-43c4-961a-25781118ba03

📥 Commits

Reviewing files that changed from the base of the PR and between ca1d3e0 and a1ec53e.

📒 Files selected for processing (5)

build.gradle
docs/design/kangcheolung-#93-mcp-server-skeleton.md
src/main/java/com/opensource/docgrid/domain/mcp/tool/DocGridMcpTools.java
src/main/java/com/opensource/docgrid/global/config/SecurityConfig.java
src/main/resources/application.yml

coderabbitai · 2026-08-05T07:11:17Z

+@Component
+public class DocGridMcpTools {


📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

DocGridMcpTools의 역할과 경계를 설명하는 Javadoc을 추가해 주세요.

이 클래스는 새로 생성되었지만 클래스 수준 주석이 없습니다. MCP 프로토콜 입력·출력 경계만 담당하고 검색·권한·문서 조회 규칙은 도메인 서비스에 위임한다는 역할을 명시하세요.

제안

+/** + * DocGrid 문서 조회 기능을 MCP 도구로 노출하는 어댑터다. + * + * 프로토콜 경계만 담당하고 검색·권한·문서 조회 규칙은 도메인 서비스에 위임한다. + */ `@Component` public class DocGridMcpTools {

As per coding guidelines: “Every newly created class, interface, or record must have a class-level comment explaining its role, responsibility, and boundary.”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

@Component

public class DocGridMcpTools {

/**

* DocGrid 문서 조회 기능을 MCP 도구로 노출하는 어댑터다.

*

* 프로토콜 경계만 담당하고 검색·권한·문서 조회 규칙은 도메인 서비스에 위임한다.

*/

`@Component`

public class DocGridMcpTools {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/main/java/com/opensource/docgrid/domain/mcp/tool/DocGridMcpTools.java` around lines 7 - 8, DocGridMcpTools 클래스에 클래스 수준 Javadoc을 추가하여 MCP 프로토콜의 입력·출력 경계만 담당하고 검색, 권한, 문서 조회 규칙은 도메인 서비스에 위임한다는 역할과 책임 범위를 명시하세요.

Source: Coding guidelines

annotations 속성을 생략하면 SDK 기본값(readOnlyHint=false, destructiveHint=true)이 그대로 노출되어 조회 전용 도구가 파괴적 작업처럼 클라이언트에 선언되는 문제를 수정한다.

JSON 코드블록 안의 주석을 밖으로 빼고, readOnlyHint/destructiveHint 항목을 '다음 이슈' TODO에서 '이번 이슈 반영 완료'로 옮긴다.

kangcheolung added 4 commits August 5, 2026 15:59

feat: MCP 서버 의존성 및 Streamable HTTP 설정 추가

b5917be

spring-ai-bom 1.1.8 기반 spring-ai-starter-mcp-server-webmvc를 도입하고 protocol=STREAMABLE, annotation-scanner.enabled=true로 설정한다.

feat: MCP 도구 3종 스켈레톤 등록

9e67a1c

@McpTool/@McpToolParam 어노테이션 스캔이 정상 동작하는지 검증하기 위해 search_documents, get_document_detail, get_indexing_status 빈 핸들러를 등록한다. 실제 로직은 후속 이슈에서 구현한다.

chore: MCP 엔드포인트 임시 인증 예외 처리

1d99c5d

/mcp/** 를 임시로 permitAll 처리한다. API 키 인증 필터(McpApiKeyAuthFilter)는 다음 이슈에서 구현 후 이 예외를 교체한다.

docs: #93 MCP 서버 골격 설계 문서 추가

a1ec53e

Spring AI 1.1.x 채택 근거, javap로 검증한 SDK 내부 구조(패키지 경로, 설정 프로퍼티, #4882/#4392 회피 경로), tools/list 실제 검증 결과를 기록한다.

Merge remote-tracking branch 'origin/develop' into feature/93

c0679af

# Conflicts: # src/main/resources/application.yml

coderabbitai Bot reviewed Aug 5, 2026

View reviewed changes

kangcheolung added 2 commits August 5, 2026 16:16

fix: MCP 도구 readOnlyHint/destructiveHint 명시

bb22f1b

annotations 속성을 생략하면 SDK 기본값(readOnlyHint=false, destructiveHint=true)이 그대로 노출되어 조회 전용 도구가 파괴적 작업처럼 클라이언트에 선언되는 문제를 수정한다.

docs: #93 CodeRabbit 리뷰 반영 - JSON 예시 주석 제거 및 TODO 갱신

b41887b

JSON 코드블록 안의 주석을 밖으로 빼고, readOnlyHint/destructiveHint 항목을 '다음 이슈' TODO에서 '이번 이슈 반영 완료'로 옮긴다.

kangcheolung merged commit 08bd034 into develop Aug 5, 2026
1 check passed

Navigation Menu

Uh oh!

[Feat] MCP 서버 골격 및 도구 3종 스켈레톤 등록 - #95

[Feat] MCP 서버 골격 및 도구 3종 스켈레톤 등록#95
kangcheolung merged 7 commits into
developfrom
feature/93

kangcheolung commented Aug 5, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Aug 5, 2026 •

edited

Loading

Review limit reached

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

coderabbitai Bot Aug 5, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

kangcheolung commented Aug 5, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

배경

변경 사항

검증

문서

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

kangcheolung commented Aug 5, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Aug 5, 2026 •

edited

Loading