Skip to main content
Glama

NAVER WORKS MCP

Hermes에서 자연어로 NAVER WORKS의 일정·연락처·구성원 정보를 조회하게 해 주는 MCP 서버입니다. 처음에는 안전한 읽기 전용으로 동작하며, MCP 프로토콜 2026-07-28의 무상태 HTTP 규칙과 로컬 stdio 연결을 함께 제공합니다.

처음 사용하는 분은 비개발자용 HTML 설명서를 먼저 여세요. 화면에서 순서대로 따라 하면 됩니다.

이 프로젝트가 하는 일

  • Hermes가 MCP 도구를 호출하면 NAVER WORKS API에 읽기 요청을 보냅니다.

  • 일정 속성, 일정 목록, 연락처 검색, 조직 구성원 목록/프로필을 제공합니다.

  • 기본값은 로컬 컴퓨터에서만 실행되는 stdio입니다. 인터넷에 공개하지 않아 가장 안전합니다.

  • 실제 토큰이 없을 때는 NAVER_WORKS_MOCK=true로 연결 연습과 계약 테스트를 할 수 있습니다.

  • 메시지 보내기, 수정/삭제, Mail·Drive·Board·Task·Form 같은 기능은 현재 등록하지 않았습니다.

Related MCP server: HRIS MCP Connector

먼저 준비할 것

  1. Windows/macOS/Linux 중 하나

  2. Node.js 20.11 이상

  3. NAVER WORKS Developer Console에서 발급한 사용자 OAuth Access Token

  4. 조회할 NAVER WORKS 사용자의 userId

  5. Hermes의 MCP 서버 추가 화면

OAuth 로그인·Refresh Token 갱신·Service Account JWT 서명은 이 저장소가 담당하지 않습니다. 외부 OAuth/Secret Provider에서 발급한 Bearer Access Token을 환경 변수로 넣는 구조입니다. 토큰은 GitHub, README, HTML 파일에 절대 적지 마세요.

지원 환경과 연결 방식

환경

Hermes와 MCP 관계

권장 연결

Windows 또는 Ubuntu에 둘 다 설치

같은 컴퓨터에서 실행

stdio

Hermes만 Docker 안에서 실행

MCP도 같은 컨테이너에 포함

컨테이너 내부 stdio

Hermes와 MCP가 서로 다른 컨테이너

Docker 네트워크로 통신

내부 HTTP /mcp

외부 PC에서 접속

reverse proxy를 거치는 원격 서비스

TLS + 공유 시크릿 HTTP

운영 환경을 자동으로 판단하지 말고, 설치 지시문이 먼저 운영체제·컨테이너 여부·Hermes의 터미널 실행 가능 여부를 확인하게 하세요. 개인 PC에서는 stdio가 가장 단순하고 안전합니다.

10분 안에 로컬 연결하기

1) 소스 받기

이미 이 폴더가 있다면 이 단계는 건너뛰세요.

Windows PowerShell:

git clone https://github.com/QriumJ/NAVER_WORKS_MCP.git NAVER_WORKS_MCP
Set-Location NAVER_WORKS_MCP

Ubuntu:

git clone https://github.com/QriumJ/NAVER_WORKS_MCP.git NAVER_WORKS_MCP
cd NAVER_WORKS_MCP

현재 완성본은 GitHub main에 병합되어 있습니다. 특정 개발 브랜치를 시험할 때만 --branch 브랜치명을 추가하세요.

2) 설치하고 설정 파일 만들기

Windows PowerShell:

npm install
Copy-Item .env.example .env

Ubuntu:

npm install
cp .env.example .env

.env를 메모장으로 열어 먼저 연습 모드로 확인합니다.

MCP_TRANSPORT=stdio
NAVER_WORKS_MOCK=true
NAVER_WORKS_USER_ID=mock-user

3) 빌드와 테스트

Windows PowerShell 또는 Ubuntu:

npm run build
npm test

22 passing이 나오면 프로그램 자체는 정상입니다.

4) Hermes에 서버 등록

Hermes의 MCP 서버 추가 화면에서 전송 방식은 stdio를 선택하고, 아래처럼 현재 운영체제의 절대 경로를 넣습니다. Hermes 버전에 따라 항목 이름이 command, args, env 또는 실행 파일, 인자, 환경 변수로 보일 수 있습니다.

Windows:

{
  "name": "naver-works",
  "command": "node",
  "args": ["C:\\Users\\Home\\Documents\\네이버웍스\\dist\\index.js"],
  "env": {
    "MCP_TRANSPORT": "stdio",
    "NAVER_WORKS_MOCK": "true",
    "NAVER_WORKS_USER_ID": "mock-user"
  }
}

Ubuntu:

{
  "name": "naver-works",
  "command": "node",
  "args": ["/home/your-user/NAVER_WORKS_MCP/dist/index.js"],
  "env": {
    "MCP_TRANSPORT": "stdio",
    "NAVER_WORKS_MOCK": "true",
    "NAVER_WORKS_USER_ID": "mock-user"
  }
}

args의 경로는 실제 폴더에 맞게 바꾸세요. Windows는 C:\...\\dist\index.js, Ubuntu는 /home/.../dist/index.js처럼 운영체제의 절대 경로를 사용합니다. Hermes에 cwd(작업 폴더) 항목이 있다면 이 프로젝트 폴더를 지정하면 .env도 자동으로 읽습니다.

5) Hermes에서 확인

서버를 저장하고 Hermes 채팅에서 다음처럼 말해 보세요.

NAVER WORKS에서 내 프로필을 조회해 줘.

연습 모드에서는 mock-user가 반환됩니다. 응답이 오면 Hermes ↔ MCP 연결은 끝난 것입니다.

Hermes 채팅으로 설치시키는 지시문

Hermes가 터미널과 파일을 실행할 수 있다면 아래 지시문 전체를 Hermes 채팅에 붙여 넣으세요. Hermes가 실행 권한을 지원하지 않는 경우에는 명령을 대신 보여 달라고 요청하고, 이 README의 명령을 직접 실행하면 됩니다.

내 환경을 먼저 확인한 뒤 NAVER WORKS MCP를 설치하고 Hermes에 연결해 줘.

규칙:
1. 운영체제가 Windows인지 Ubuntu/Linux인지, Hermes가 Docker 컨테이너 안에서 실행 중인지, 터미널·파일 실행 권한이 있는지 먼저 확인하고 결과를 알려 줘.
2. Node.js 20.11 이상, npm, Git이 설치되어 있는지 확인해. Docker라면 Docker 이미지에서 Node.js 22 이상을 사용해.
3. 기존 저장소가 있으면 파일을 삭제하지 말고 현재 변경사항과 브랜치를 먼저 확인해.
4. 저장소가 없으면 기본 `main`을 내려받아. Windows는 PowerShell 경로, Ubuntu는 bash 경로를 사용해:
   git clone https://github.com/QriumJ/NAVER_WORKS_MCP.git NAVER_WORKS_MCP
5. 저장소 폴더에서 npm install과 npm run build를 실행해. Docker라면 Dockerfile 또는 compose.yaml을 사용해.
6. 실제 토큰을 요구하거나 출력하지 말고, NAVER_WORKS_MOCK=true로 npm test를 실행해 22개 테스트 결과를 확인해.
7. Hermes와 MCP가 같은 환경이면 stdio를 사용해. 다른 Docker 컨테이너라면 MCP를 compose.yaml의 HTTP 서비스로 띄우고 Hermes에는 http://naver-works-mcp:8787/mcp를 설정해.
8. HTTP Docker 서비스는 MCP_HOST=0.0.0.0, 32자 이상 MCP_SHARED_SECRET, MCP_ALLOWED_HOSTS에 실제 서비스 이름을 설정하고 외부 공개 시 TLS reverse proxy를 사용해. 공유 시크릿을 채팅에 출력하지 마.
9. 설치·빌드·테스트·등록 결과를 단계별로 보고하고, 실패하면 원인과 다음 명령만 알려 줘.
10. NAVER_WORKS_ACCESS_TOKEN, 비밀번호, 개인정보를 채팅에 출력하거나 Git에 커밋하지 마.
11. 실제 NAVER WORKS 연결은 내가 별도로 OAuth 토큰을 준비했다고 말한 뒤에만 진행해. 그때도 토큰 값은 화면에 다시 출력하지 말고 환경 변수나 Secret Manager에만 저장해.
12. 쓰기·삭제·메시지 전송 기능은 추가하지 말고, 현재 읽기 전용 도구만 등록해.

Hermes가 “설치 완료”라고 답하면 채팅에서 NAVER WORKS에서 내 프로필을 조회해 줘라고 테스트하세요. 실제 데이터를 연결할 때만 NAVER_WORKS_MOCK=false와 외부 Token Provider가 발급한 Access Token을 설정합니다.

Docker에서 Hermes와 연결하기

A. Hermes와 MCP가 같은 Docker 컨테이너에 있을 때

이미지를 빌드한 뒤 stdio 프로세스로 실행합니다. MCP 프로토콜은 줄바꿈 기반이므로 -i를 사용하고 -t(가상 터미널)는 붙이지 않습니다.

Windows PowerShell:

docker build -t naver-works-mcp:local .
docker run --rm -i --env-file .env naver-works-mcp:local node dist/index.js

Ubuntu:

docker build -t naver-works-mcp:local .
docker run --rm -i --env-file .env naver-works-mcp:local node dist/index.js

Hermes가 Docker 밖에 있고 Docker MCP를 자식 프로세스로 실행할 수 있으면 Hermes의 stdio 설정을 command=docker로, 인자를 run --rm -i --env-file <절대경로>/.env naver-works-mcp:local node dist/index.js로 지정합니다.

B. Hermes와 MCP가 서로 다른 Docker 컨테이너일 때

이 저장소의 compose.yaml은 MCP를 HTTP 서비스로 띄우고, 호스트에는 loopback으로만 포트를 공개합니다. 먼저 .env에 32자 이상의 MCP_SHARED_SECRET을 직접 생성해 넣으세요.

Windows PowerShell:

Copy-Item .env.example .env
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
docker compose up --build

Ubuntu:

cp .env.example .env
openssl rand -hex 32
docker compose up --build

출력한 랜덤 문자열은 .envMCP_SHARED_SECRET 값으로만 저장합니다. 다른 컨테이너의 Hermes는 서비스 이름을 사용해 http://naver-works-mcp:8787/mcp에 연결하고, X-MCP-Shared-Secret 헤더를 보냅니다. Hermes가 MCP 2026-07-28 HTTP envelope를 지원하지 않으면 B 방식 대신 A 방식(stdio)을 사용하세요.

실제 NAVER WORKS API 연결

1) Developer Console에서 확인

앱의 사용자 OAuth 권한에 다음 읽기 Scope를 요청합니다.

calendar.read
contact.read
directory.read
user.profile.read

조직 정책에 따라 관리자 승인과 Redirect URL 등록이 필요할 수 있습니다. 실제 토큰은 OAuth 로그인 후 외부 Token Provider에서 발급받으세요.

2) .env에 실제 값 입력

MCP_TRANSPORT=stdio
NAVER_WORKS_MOCK=false
NAVER_WORKS_ACCESS_TOKEN=여기에_짧은_수명의_Bearer_토큰
NAVER_WORKS_USER_ID=조회할_사용자_ID
NAVER_WORKS_AUTH_MODE=user_oauth
NAVER_WORKS_API_BASE=https://www.worksapis.com/v1.0
NAVER_WORKS_ENFORCE_SCOPES=true
NAVER_WORKS_SCOPES=calendar.read,contact.read,directory.read,user.profile.read

토큰 앞에 Bearer 를 붙이지 마세요. 서버가 요청 헤더에 자동으로 붙입니다. 토큰을 바꾼 뒤 Hermes를 완전히 다시 시작해야 새 환경 변수가 반영됩니다.

HTTP로 연결하고 싶은 경우(고급)

대부분의 개인 사용자는 stdio를 권장합니다. 다른 컴퓨터나 원격 Hermes가 연결해야 할 때만 HTTP를 사용하세요.

Windows PowerShell:

npm run build
$env:MCP_TRANSPORT="http"
$env:MCP_HOST="127.0.0.1"
$env:MCP_PORT="8787"
node dist/index.js

Ubuntu:

npm run build
MCP_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=8787 node dist/index.js

정상 실행 후 http://127.0.0.1:8787/healthz에서 상태를 확인할 수 있습니다. HTTP /mcp는 MCP 2026-07-28 strict stateless envelope와 표준 헤더를 요구합니다. 원격 바인딩은 32자 이상의 MCP_SHARED_SECRET, 허용 Host 목록, TLS reverse proxy가 모두 필요합니다. 공유 시크릿 없이 인터넷에 공개하지 마세요.

제공되는 도구

도구

쉬운 설명

works_health

NAVER WORKS API 연결 상태 확인

works_calendar_default_properties

기본 캘린더 목록

works_calendar_personals_list

개인 캘린더 목록

works_calendar_default_events_list

기본 캘린더 일정

works_calendar_events_list

지정 캘린더 일정

works_contact_search_minimal

이름·전화·이메일로 연락처 검색

works_directory_users_list

조직 구성원 목록

works_directory_user_profile_get

한 명의 최소 프로필 조회

PII는 필요한 최소 필드만 반환하고, 쓰기·삭제 도구는 의도적으로 없습니다.

자주 생기는 문제

증상

해결

node를 찾을 수 없음

Windows/Ubuntu에 Node.js 20.11 이상을 설치하거나 Docker 이미지의 Node.js 22 이상을 사용

dist/index.js가 없음

프로젝트 폴더에서 npm run build 실행

토큰이 없다는 오류

.env 또는 Hermes envNAVER_WORKS_ACCESS_TOKEN 입력

Scope 부족(403)

Developer Console 권한과 실제 토큰 Scope를 확인하고 새 토큰 발급

Hermes가 도구를 못 봄

command는 node, args는 dist/index.js 전체 경로인지 확인

실제 데이터 대신 mock-user가 나옴

NAVER_WORKS_MOCK=false로 바꾸고 Hermes 재시작

Docker에서 HTTP가 바로 종료됨

MCP_HOST=0.0.0.0, 32자 이상 MCP_SHARED_SECRET, MCP_ALLOWED_HOSTS 서비스 이름을 확인

Docker 컨테이너끼리 연결 안 됨

localhost 대신 Compose 서비스 이름 naver-works-mcp를 사용

HTTP 401/403

MCP_SHARED_SECRET, Host/Origin 허용 목록, TLS 프록시 설정 확인

검수 및 문서

npm run build
npm test
npm audit --omit=dev

현재 검수 결과는 98/100, P0/P1 결함 없음입니다. 남은 항목은 포트 문자열의 더 엄격한 파싱, 실테넌트 권한 검증, 실제 Hermes 클라이언트의 2026-07-28 지원 확인 같은 운영 단계입니다.

Available Tools

8 tools
works_calendar_default_events_list기본 캘린더 일정 조회B

최대 31일 범위의 기본 캘린더 일정을 읽기 전용으로 조회합니다. 설명·참석자·외부 지시는 제거합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
userIdNo
fromDateTimeYes
untilDateTimeYes

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the transparency burden. It discloses that this is read-only and that descriptions, attendees, and external directives are stripped from results. This adds meaningful behavioral context, though it doesn't elaborate on the 31-day range outcome (e.g., what happens if the range exceeds it) or the return format. Moderate but acceptable given no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise Korean sentence that packs the read-only nature, 31-day scope, and data stripping behavior with minimal waste. It earns points for being front-loaded and efficient, though it is arguably under-specified rather than over-long.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is moderately complex with 3 parameters, no output schema, and no annotations. The description covers the read-only and data-stripping aspects but leaves the parameter semantics, return value shape, and differentiation from sibling calendar tools unaddressed. For a tool with no output schema and 0% schema coverage, this is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for all 3 parameters. It does not explain the format or meaning of fromDateTime/untilDateTime beyond what the schema patterns imply, nor does it clarify the optional userId parameter (whose calendar? defaulting behavior). The 31-day limit is mentioned but not tied to the date parameters explicitly. This is a significant gap for a 0%-coverage schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource+scope: '조회합니다' (retrieves) default calendar events within a max 31-day range. It's clear in purpose. However, it doesn't explicitly distinguish itself from the sibling 'works_calendar_events_list' tool, which could be its general counterpart, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the read-only nature and the 31-day constraint, giving some usage context (read-only query). However, there is no explicit guidance on when to use this vs the sibling 'works_calendar_events_list' or 'works_calendar_personals_list', nor any mention of prerequisites. Usage context is implied but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

works_calendar_default_properties기본 캘린더 속성 조회C

구성원의 기본 캘린더 속성을 조회합니다. 일정 설명·참석자 등 원문은 반환하지 않습니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
userIdNo

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses that original text (descriptions, attendees) is not returned, which is useful. However, it doesn't disclose whether this is read-only, what happens if userId is invalid/absent, response format, or auth/permission requirements. Since userId is not required (0 required params), it's unclear what happens without it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence plus a clarifying exclusion clause. Both sentences earn their place—the first states the purpose, the second clarifies limitations. No fluff, though it could be slightly more informative within its brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations, no output schema, only 1 param (0 required), and 0% schema coverage, the description should do significantly more. It clarifies what's NOT returned but doesn't state what IS returned, whether userId is optional, error behavior, or how this relates to sibling calendar tools. For a read-type query tool, critical behavioral gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and there is only one parameter (userId) with a minLength=1 constraint but no description. The tool description mentions '구성원' (member) implying userId refers to a member, but it doesn't explain what values are valid (email, internal id, etc.) or whether the parameter is optional despite being schematically not required. The description adds little meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it queries a member's default calendar properties and clarifies it does not return original text like event descriptions or attendees. The verb '조회' (query/inquire) plus '기본 캘린더 속성' (default calendar properties) specifies the resource clearly. It doesn't explicitly differentiate from sibling tools, though the title implies a default-calendar scope distinct from the personal/events list tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives. It doesn't mention whether this is called before creating events, paired with events-list tools, or what prerequisite context is needed. The description only clarifies what it does NOT return, but gives no when-to-use or when-not-to-use instructions relative to the sibling calendar and directory tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

works_calendar_events_list명시적 캘린더 일정 조회C

calendarId가 명시된 캘린더의 일정을 최대 31일 범위로 조회합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
userIdNo
calendarIdYes
fromDateTimeYes
untilDateTimeYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only mentions a 31-day limit, but does not state pagination behavior, session/permission requirements, whether results are sorted, what happens when the range exceeds 31 days (error vs truncation), or the return format. For a read tool with zero annotation coverage, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single, clean sentence in Korean that front-loads the core action and scoping. It is appropriately succinct without wasted words, though it could add a reference to sibling alternatives without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations, no output schema, 0% parameter coverage, and 4 undocumented parameters, the description is far from complete. It doesn't clarify the 31-day boundary behavior, the relationship to default/personal calendar listing siblings, or the purpose of userId. For a calendar-list tool with multiple related siblings, this is inadequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for all 4 parameters. However, it only references calendarId implicitly (via 'calendarId가 명시된'). fromDateTime, untilDateTime, and userId semantics are entirely unexplained—including the ISO8601 format, the relationship between from/until, and whether userId is required for cross-user access.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states the verb (조회/list), resource (calendar events), and a key scoping constraint (calendarId가 명시된 캘린더, explicit calendar). The '최대 31일 범위' adds a meaningful boundary. However, it doesn't distinguish itself from the sibling tool works_calendar_default_events_list, which likely serves a similar purpose for default calendars.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for calendars with an explicit calendarId (contrasting with 'default' calendar tools among siblings), but provides no explicit when/when-not guidance or named alternatives. The 31-day max range is a useful constraint but no filtering semantics or exclusions are described.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

works_calendar_personals_list개인 캘린더 목록 조회C

사용자가 접근 가능한 캘린더의 개인 속성을 커서 기반으로 조회합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
countNo
cursorNo
userIdNo

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description discloses cursor-based pagination but omits critical behaviors: whether the 'personal attributes' returned are read-only, what each page returns, whether results include the current user's calendar plus those shared with them, and whether this is a safe read operation. For a list endpoint with no annotations, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that uses efficient Korean phrasing. It front-loads the purpose and includes the pagination mechanism. It's economical, though it could add a second sentence for behavioral/usage context without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, the description must provide completeness, but it falls short. The term 'personal attributes' (개인 속성) is ambiguous, the tool has 3 parameters at 0% schema coverage, and siblings like works_calendar_default_properties need differentiation. For a 3-parameter list tool with zero structured metadata support, this description is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the three parameters (count, cursor, userId). It mentions 'cursor' concept generally but does not explain what userId controls (likely filtering to a specific user's calendars), how count interplays with pagination, or the meaning of the cursor parameter beyond vague 'cursor-based' mention. The description adds only marginal value over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool lists personal attributes of accessible calendars using cursor-based pagination. However, 'personal properties' is vague - it doesn't specify WHAT personal attributes are returned (e.g., sharing settings, ownership, color, notifications). It distinguishes from event-focused siblings (events_list) but not clearly from default_properties sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives. The title says 'personal calendar list' and mentions cursor-based pagination, which implies a listing use case, but there's no explicit statement of when to choose this over works_calendar_default_properties or why 'personals' differ from 'defaults'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

works_contact_search_minimal연락처 최소 필드 검색B

연락처를 검색하고 이메일·전화번호는 마스킹된 최소 필드만 반환합니다. memo·주소·커스텀 속성은 제외합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
countNo
queryYes
cursorNo
userIdNo
orderByNoname asc
queryFiltersNo

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses that output is minimal and masking occurs, which is useful behavioral context. However, it doesn't disclose pagination behavior, result ordering defaults, or what happens with invalid queries/missing matches.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single concise sentence that packs useful information about scope, masking, and exclusions. No wasted words, though it could arguably be a bit longer to cover parameter semantics.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A 6-parameter search tool with 0% schema coverage, no annotations, and no output schema. The description is too thin: it doesn't explain query semantics, pagination, filtering, ordering behavior, or the output shape. For a complex search tool, significantly more behavioral documentation is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for all 6 parameters. It fails to do so — none of the parameters (query, count, cursor, userId, orderBy, queryFilters) are explained beyond the schema. The description adds no meaning about the query format, filter syntax, or cursor semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool searches contacts and returns only minimal fields with masked email/phone, excluding memo/address/custom properties. The verb+resource is clear and it distinguishes from directory tools, though it doesn't explicitly name sibling alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for searching contacts when minimal/masked data suffices, and signals that richer fields (memo, address, custom attributes) are excluded. However, it doesn't explicitly state when to prefer this over alternatives like works_directory_users_list or provide when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

works_directory_user_profile_get구성원 최소 프로필 조회B

이미 알고 있는 userId의 최소 프로필을 조회합니다. Service Account의 userId=me는 차단합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
userIdYes

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations, so the description carries the disclosure burden. The main behavioral disclosure is that userId=me is blocked for Service Accounts, which is valuable. However, it doesn't state whether this is a read-only operation, potential failure modes (e.g., unauthorized users, unknown IDs), or response shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, tight sentence plus a short constraint clause. It's efficient with no filler. Slightly more detail would be acceptable, but the current wording is appropriately compact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations, no output schema, and a single opaque parameter, the description must carry more weight. It fails to mention what fields the minimal profile returns, prereducuate requirements (auth level), or error behavior. For a single-parameter lookup tool this is on the thinner side, though the 'already known userId' framing helps scope it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has a single self-explanatory parameter (userId) with 0% schema description coverage. The description reinforces that the ID must be 'already known' and that 'me' is invalid for Service Accounts, which adds slight meaning beyond the bare schema. But the schema itself is minimal, so the description does not heavily enrich parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource: it queries a user's minimal profile using a known userId. It's reasonably clear, though differentiating from sibling tools like works_directory_users_list or works_contact_search_minimal is not addressed, so it doesn't fully distinguish itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description notes a precondition ('already know the userId') and an exclusion (blocks userId=me for Service Account), which is useful guidance. However, it doesn't clarify when to use this minimal-profile tool vs a full-profile or user-list alternative among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

works_directory_users_list구성원 최소 필드 목록C

구성원 목록을 커서 기반으로 조회하고 개인 이메일·전화·생년월일 등 민감 필드는 반환하지 않습니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
countNo
cursorNo
orderByNoCREATED_TIME
domainIdNo
sortOrderNoASCENDING
searchFilterTypeNo

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With zero annotations provided, the description carries full burden for behavioral disclosure. It does disclose that sensitive fields (email, phone, birth date) are NOT returned, which is useful. However, it doesn't convey rate limits, pagination behavior specifics (page size defaults, cursor exhaustion), or what the 'minimal fields' actually are. For a multi-user data access tool, this is thin behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that conveys the core purpose and the notable security constraint. It's front-loaded with the main action. However, it's arguably under-specified rather than efficiently complete — every word earns its place but there's simply not enough content given the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 6 parameters (including an undocumented searchFilterType with a 'VIP' const), 0% schema coverage, no annotations, and no output schema, this description is substantially incomplete. While it's a data retrieval operation (less risky than mutation), the agent will struggle to know what 'minimal fields' contains, what VIP filtering means, how cursor pagination flows, and what the output shape is.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for documenting 6 parameters. The description mentions cursor-based pagination (covering 'cursor') and sensitive field exclusion, but explains nothing about searchFilterType (VIP filter semantics), domainId, orderBy, sortOrder, or count. The description adds minimal value beyond what parameter names alone convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it lists members with cursor-based pagination and explicitly omits sensitive fields. However, it doesn't clearly distinguish what this 'minimal field list' means compared to sibling tools beyond the mention of sensitive field exclusion. The verb '조회' (query/retrieve) plus '구성원 목록' (member list) and '커서 기반' (cursor-based) gives reasonable purpose clarity, but lacks differentiation from the sibling list/contact tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There's no guidance on when to use this tool versus alternatives like works_contact_search_minimal or works_directory_user_profile_get. The description implies it's for batch member listing where sensitive fields aren't needed, but says nothing about when the cursor parameter should be used, what searchFilterType='VIP' means, or when to prefer a different tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

works_healthNAVER WORKS MCP 상태A

서버 버전, 무상태 MCP 전송, 인증 모드, Scope 정책을 비밀값 없이 확인합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states no secrets are used and checks configuration aspects, implying a safe read-only operation, but does not describe output format, response shape, or any edge-case behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single Korean sentence efficiently lists exactly what configuration aspects are verified and explicitly notes no secrets are involved. No wasted words or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter health check with a clear scope of what it reports, the description is reasonably complete. It does not mention output format, but with no output schema and a well-scoped purpose, the description covers the essential expectations adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, which the input schema already makes clear. Per the rubric, 0 params = baseline 4, and the description adds context about what information (server version, auth mode, scope policy) is being surfaced, which helps the agent know what to expect.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks server version, MCP transport statelessness, auth mode, and scope policy. This distinguishes it from sibling tools which are all resource-specific (profile, calendar, contacts) — a health/status check is clearly differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this is a diagnostic/status tool to verify server configuration without secrets, which gives some context for when to use it. However, it does not explicitly state when-not to use it or name alternatives, relying on the distinct health-related purpose.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv0.1.0
    • First observedworks_calendar_default_events_list
    • First observedworks_calendar_default_properties
    • First observedworks_calendar_events_list
    • First observedworks_calendar_personals_list
    • First observedworks_contact_search_minimal
    • First observedworks_directory_user_profile_get
    • First observedworks_directory_users_list
    • First observedworks_health

TDQS

C2.9/5.0

Scored across 8 tools

Disambiguation3/5

The tools are mostly distinct by domain (health, directory, calendar, contact), but there are two calendar event listing tools (works_calendar_default_events_list and works_calendar_events_list) that overlap significantly—both list events, differing only in whether a calendarId is specified. Similarly, directory tools for user profile vs user list are distinct enough, but the event tool overlap creates some misselection risk.

Naming Consistency3/5

The tools follow a consistent works_<domain>_<resource>_<action> pattern (e.g., works_calendar_events_list, works_directory_users_list). However, the verbs are inconsistent: some use action suffixes like 'get', 'list', 'search', 'properties', but the server name prefix 'works_' is consistently applied and the overall structure is predictable.

Tool Count4/5

8 tools is a reasonable count for a Naver Works integration server covering health, directory, calendar, and contacts. Each tool earns its place for core workflows, though the surface is slightly narrow for the breadth of domains it touches.

Completeness2/5

The server covers health checks, directory lookups, calendar event reading, and contact search, but all operations are read-only. There are no create/update/delete operations for any resource, meaning agents can only query data and cannot perform any lifecycle management. Calendar event creation, contact management, and user administration are all absent, leaving notable gaps for a 'works integration' server.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers