Skip to main content
Glama
deenesjakoruzh
utakatano

mcp-server-sample

by utakatano
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

mcp-server-sample — 메모를 저장·검색하는 최소의 MCP 서버

메모를 저장하고 검색하는 것만 가능한 최소의 MCP 서버입니다. 외부 시스템에는 전혀 연결하지 않습니다. 저장 위치는 같은 폴더의 notes.json 하나의 파일뿐입니다.

MCP의 3가지 프리미티브를 각각 하나씩 갖추고 있습니다.

프리미티브

누가 결정하는가

이 서버에서의 내용

Tools

모델이 판단한다

add_note (메모 추가)／search_notes (메모 검색)

Resources

AI 앱이 획득하여 전달한다

notes://all (저장된 메모 전)

Prompts

사욕자가 명시적으로 선택한다

weekly_review (이번 주 회고)

필요 사항

  • Node.js 24 이상 (LTS. node --version으로 확인)

  • git

Related MCP server: mcp-snippetbox

설정

git clone https://github.com/utakatano/mcp-server-sample.git
cd mcp-server-sample
npm install

npm install이 통과되면 준비 완료입니다. 이 시점에서는 시작하지 않습니다. MCP 서버는 AI 앱이 시작하기 때문에, 직접 터미널에서 실행할 필요가 없습니다.

AI 앱에 연결

Claude Code

claude mcp add notes -- node /絶対パス/mcp-server-sample/index.js

claude mcp list에서 ✔ Connected가 나타나면 연결된 것입니다.

Claude Desktop

설정 → Developer → 「Edit Config」에서 claude_desktop_config.json을 열고 다음을 추가합니다.

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/絶対パス/mcp-server-sample/index.js"]
    }
  }
}

저장한 후 Claude Desktop을 완전히 종료하고 다시 시작합니다 (창을 닫는 것만으로는 반영되지 않습니다).

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

작동 확인

「来週までにネットワーク構成を確認する」とメモして
「ネットワーク」を含むメモを探して

notes.json이 만들어지고, 내용이 느어나는 것을 확인할 수 있습니다.

저장 위취 변경

환경 변수 NOTES_FILE에 절대 경로를 전달하면 저장 위취를 변경할 수 있습니다.

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/絶対パス/mcp-server-sample/index.js"],
      "env": { "NOTES_FILE": "/絶対パス/my-notes.json" }
    }
  }
}

연결되지 않을 때

먼저 로그를 봅니다. 원인은 대개 여기에 나타납니다.

tail -20 ~/Library/Logs/Claude/mcp-server-notes.log   # macOS
# Windows: %APPDATA%\Claude\logs\mcp-server-notes.log

Server started and connected successfully 이후에 오류가 이어지지 않는지 확인하세요.

로그에 나타난 것

원인

대처

Cannot find module '/.../index.js'

args의 경로가 다름

리포지토리 직하에서 pwd를 실행하고, 그 출력 + /index.js를 다시 붙여넣기

spawn node ENOENT

AI 앱에서 node를 찾을 수 없음. nvm/volta 등으로 PATH가 셸 설정에만 있는 경우 발생

which node의 출력(절대 경로)을 command에 그대로 기재

Cannot find package '@modelcontextprotocol/server'

의존성이 설치되지 않음

리포지토리 직하에서 npm ci

로그가 비었거나 갱신되지 않음

설저이 로드되지 않음

JSON 구문(표, 괄호)을 확인하고, Claude Desktop을 완전히 종료(macOS는 ⌘Q)한 후 다시 시작

서버 측인지 AI 앱 측인지의 구분은 로컬에서 직접 실행해보는 것이 밉릅니다.

printf '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}\n' \
  | node /絶対パス/mcp-server-sample/index.js

add_note와 search_notes를 포함한 JSON이 반환되면 서버는 정상입니다. 그 경우 AI 앱 측의 설정(경로·JSON 작선법·재시작)을 의심하세요.

공급망 보안

npm 패키지 탈취를 가정한 설정을 .npmrc에 넣어 두었습니다. npm install / npm ci 할 때마다 적용됩니다.

설정

하는 일

ignore-scripts=true

설취 시 의존 패키지의 라이프사이클 스크립트(postinstall 등)를 실해하지 않음. 탈취된 패키지가 처음 사욕하는 실해 경로를 차단. npm start / npm run은 종래대로 동작(pre/post 스크립트만 실해되지 않음)

save-exact=true

npm install <pkg>가 package.json에 ^를 붙이지 않고, 완전 고정으로 작선

min-releae-age=7

공개로부터 7일이 지난 버전만 설취. npm은 이곳을 before=<7일 전의 일시>로 변환하여 의존을 해결

의존성은 package.json에서 완전 고정 (@modelcontextprotocol/server는 2.0.0, zod는 4.4.3), package-lock.json에 integrity 해시와 함께 기록되어 있습니다. lock대로 설치하려면 npm install이 아닌 npm ci를 사용하세요.

의존성을 갱신할 때는 의도적으로 하나씩 올립니다.

npm outdated
npm install @modelcontextprotocol/server@2.1.0   # save-exact により完全固定で書かれる
npm ls --all                                      # 増えた依存を目で確認する

라이선스

MIT

Available Tools

2 tools
add_noteメモを追加するA

メモを1件保存する。打ち合わせの決定事項や、あとで思い出したいことを記録するときに使う。

ParametersJSON Schema
NameRequiredDescriptionDefault
tagsNo分類用のタグ（任意）
textYes保存する本文

TDQS

A4/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 full burden. It states '保存する' which implies mutation, but it does not disclose potential side effects, permissions, or behavior on duplicates. For a simple create operation, this is minimally adequate.

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?

Two sentences, front-loaded with the essential action. No wasted words.

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 simple tool with 2 parameters, no output schema, and no annotations, the description is fairly complete. It explains the primary use case and differentiates from the sibling. It could mention the return value but is not required.

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?

Schema description coverage is 100% with both parameters described. The tool's description adds no new information about the parameters; it only restates the purpose. Baseline 3 is appropriate.

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

Purpose5/5

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

The description clearly states the verb '保存する' (save) and resource 'メモ' (note), and it is distinct from the sibling tool 'search_notes' which is for retrieval.

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

Usage Guidelines4/5

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

It provides explicit context for when to use: '打ち合わせの決定事項や、あとで思い出したいことを記録するときに使う' (use when recording meeting decisions or things you want to remember later). It does not explicitly exclude other scenarios, but the purpose is clear.

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

search_notesメモを検索するB

保存済みのメモをキーワードで検索する。本文とタグの両方を対象にする。

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordYes検索キーワード

TDQS

B3.2/5.0
Behavior2/5

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

No annotations are provided, so the description must fully disclose behavioral traits. It states search targets both body text and tags, but lacks details on whether searches are case-sensitive, support partial matches, or have rate limits. It does not mention return format or pagination. The description adds modest value but is insufficient for a tool lacking annotations.

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?

The description is a single sentence with no wasted words. It is concise and front-loaded with the action and target, then expands on scope. Every phrase adds value.

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

Completeness3/5

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

Given the tool is simple (1 parameter, no output schema, no nested objects), the description is minimally adequate. It covers the search target and scope. However, it omits any mention of results behavior (e.g., whether it returns full notes or summaries) and does not compensate for missing annotations, but the low complexity reduces the burden.

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?

Schema coverage is 100% with one parameter 'keyword'. The description adds meaningful context by specifying that keyword searches both body and tags, which the schema description ('検索キーワード') does not convey. This enriches the semantic understanding beyond the schema alone.

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 specifies the action (検索する), the target (保存済みのメモ), and the search scope (本文とタグの両方). It distinguishes from add_note, which creates notes. However, it does not explicitly contrast the two, leaving a slight gap in sibling differentiation.

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?

The description implies usage for keyword search but gives no guidance on when to use this vs. add_note, nor does it mention any context or prerequisites for searching. No exclusion criteria or alternative scenarios are provided.

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. 2 tool updatesv1.0.0
    • First observedadd_note
    • First observedsearch_notes
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have completely distinct purposes: one creates/ stores a note, the other retrieves notes via search. There is no overlap or ambiguity between writing and searching.

Naming Consistency5/5

Both tool names follow a consistent verb_noun pattern (add_note, search_notes) using lowercase with underscores. The naming is predictable and clear.

Tool Count3/5

With only 2 tools, the set feels minimal. While the tools cover basic create and read/search operations, the server's purpose (saving and retrieving notes) could reasonably include more tools (e.g., update, delete, list tags) to avoid being overly thin.

Completeness2/5

The domain is a personal note-taking system, but only add and search operations are provided. Missing critical operations like update, delete, and get all notes (without search) create significant gaps that would frustrate or block a typical agent workflow.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers