Skip to main content
Glama
Sign In
deenesjakoruzh
toy-mcp-server

toy-mcp-server

by kritikatripathi03
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

toy-mcp-server

MCPが実際にどう動くのかを学ぶためにゼロから作った、最小限のModel Context Protocol (MCP)サーバーです。ボイラープレート生成ツールもテンプレートも使わず、素のSDKだけを使います。

最初の実践的なMCPプロジェクトとして、2つのツールと1つのリソースをstdio経由でClaude Desktopに組み込みました。

何ができるのか

MCPを使うと、LLMクライアント（Claude Desktopなど）は、トレーニングデータからテキストを生成するだけでなく、自分のマシン上で実行されている関数を呼び出せます。このサーバーが公開しているものは次のとおりです。

ツール（Claudeが呼び出せる関数）:

  • roll_dice — 面数を設定できるサイコロをN個振る

  • flip_coin — コインをN回投げる

リソース（Claudeが取得できる読み取り専用データ）:

  • server-info — サーバーの基本メタデータ（名前、目的、開始時刻）

Related MCP server: Random-Generator

なぜこれを作ったのか

LLMは自分のトレーニングデータの外側にはアクセスできず、デフォルトでは何も実行できません。ただテキストを生成するだけです。MCPはモデルに次のものを与える標準的な方法です。

  • 能力 — 単体では持っていない機能（例：真の乱数性。LLMは自分でランダムな数字を選ぶのが非常に苦手）

  • アクセス — 知る術のないライブデータや非公開データへのアクセス

このプロジェクトは、MCPサーバーを本番環境（データベースや認証付きAPIなど）に接続する前に、そのアイデア本番で試すための小さくて安全なサンドボックスです。

技術スタック

  • TypeScript

  • @modelcontextprotocol/sdk — 公式MCP SDK

  • zod — ツール引数のランタイムスキーマ検証

  • stdioトランスポート（Claude Desktopとのローカルサブプロセス通信）

プロジェクト構成

toy-mcp-server/
├── src/
│   └── index.ts       # server setup, tools, and resource
├── build/              # compiled output (git-ignored)
├── package.json
├── tsconfig.json
└── README.md

セットアップ

1. 依存関係のインストール

npm install

2. ビルド

npm run build

3. Claude Desktopに接続する

Claude Desktopの設定ファイルを探します。

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

  • Windows: 通常は %LOCALAPPDATA%\Packages\<Claude package folder>\LocalCache\Roaming\Claude\claude_desktop_config.json にあります。正確なパスはインストール方法（Microsoft Storeなのか直接インストーラーなのか）によって異なる場合があります。確実な見つけ方は、Claude Desktopを開いて 設定 → 開発者 → ローカルMCPサーバー → 設定を編集 を開くことです。これでアプリが実際に読み込んでいる正確なファイルが開きます。

このサーバーを mcpServers の下に追加します（既存のファイルを上書きせず、マージしてください）:

{
  "mcpServers": {
    "toy-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/toy-mcp-server/build/index.js"]
    }
  }
}

パスは、お使いのマシン上の build/index.js の実際の絶対パスに置き換えてください。Windowsでは、JSON文字列内のバックスラッシュを \\ のようにエスケープしてください。

4. Claude Desktopを再起動する

ウィンドウを閉じるだけではなく、完全に終了してから開き直します。設定 → 開発者 → ローカルMCPサーバー で toy-mcp-server が接続済みと表示されていることを確認してください。

5. 試してみる

チャットで次のように尋ねてみます。

  • 「6面サイコロを3個振って」

  • 「コインを10回投げて」

応答の上に小さなツール呼び出しインジケーター（例：「Roll Dice」）が表示されていれば、Claudeが答えを推測するのではなく、実際に関数を呼び出したことを確認できます。

簡単に仕組みを説明すると

  • McpServer — 接続してくるクライアントに対してサーバーの機能を宣言するオブジェクトです。

  • registerTool(name, config, handler) — 呼び出し可能な関数を登録します。config.inputSchemaは、ハンドラーが実行される前にモデルが送ってきた引数をZodで検証します。

  • registerResource(uri, config, handler) — URIで指定できる読み取り専用データを登録します。引数なしで取得されます。

  • StdioServerTransport — 通信プロトコルの役割を担います。Claude Desktopはこのファイルをサブプロセスとして起動し、JSON-RPCを使いstdin/stdoutで通信します。ここではconsole.logをログに使いません。stdoutは実際のプロトコルの通信路だからです。代わりにconsole.error（stderr）を使ってログを出します。

次のステップ

  • おもちゃのツールを、実際のデータベース（Prisma経由のPostgres）を操作する本番ツールに置き換える

  • GitHubバックエンドのツール（例：list_open_prs）を追加して、トークン認証を試す

  • ローカルで動かすのではなくリモートでホストするために、Streamable HTTPトランスポートを試す

ライセンス

MIT

Available Tools

2 tools
flip_coinFlip CoinB

Flip a coin one or more times

NameRequiredDescriptionDefault
timesNoNumber of flips

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations, the description carries the full burden of disclosing behavior. It merely says 'Flip a coin one or more times' without mentioning that the outcome is random, what the return format is (e.g., 'heads'/'tails'), or any side effects. The agent is left to guess the result structure.

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, efficient sentence that states the action and the parameter scope. There is zero wasted text, and the core information is front-loaded. It is appropriately concise for a trivial tool.

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?

Given there is no output schema, the description should explain what the tool returns (e.g., results of each flip). It omits any mention of return values or randomness, leaving the agent with incomplete information to use the tool correctly. For a tool this simple, more context is still needed.

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 single parameter 'times' is fully described in the schema ('Number of flips'), covering 100% of parameters. The tool description repeats the concept ('one or more times') but adds no extra meaning beyond what the schema already provides, so the baseline score of 3 applies.

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 states a specific verb and resource ('Flip a coin') and adds the scope 'one or more times', which distinguishes it from the sibling roll_dice by naming the object of the action. An agent can clearly identify what this tool does.

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 is given about when to use this tool versus roll_dice. The description only states the action, leaving the agent to infer from the name that this is for coins rather than dice. No exclusions, prerequisites, or alternative-routing hints are provided.

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

roll_diceRoll DiceB

Roll one or more dice with a given number of sides

NameRequiredDescriptionDefault
countNoNumber of dice to roll
sidesNoNumber of sides per die

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It does not mention that the result is random, that it is a safe non-mutating operation, or any other behavioral trait beyond the literal act of rolling. This is a significant gap for a tool whose entire purpose is random generation.

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 with no waste. The core action is front-loaded. It is appropriately sized for a tool with only two parameters, though it could have been slightly more informative without losing conciseness.

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?

For a simple tool with two parameters fully documented in the schema, the description is reasonably complete. However, the lack of any mention of randomness or return behavior (even though no output schema is provided) leaves a small but notable gap. An agent might not know the outcome is random without prior knowledge.

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%, so the schema already documents both parameters (count and sides) with defaults, minimums, and maximums. The description adds no semantic meaning beyond what the schema provides, which meets the baseline of 3.

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 states exactly what the tool does: 'Roll one or more dice with a given number of sides'. It uses a specific verb (roll) and resource (dice), and clearly distinguishes from the sibling flip_coin, since dice and coins are different objects.

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 versus the sibling flip_coin. The context implies dice vs coin, but the description does not explicitly state that this is for dice and flip_coin is for coins, nor does it mention any exclusions or alternative conditions.

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 observedflip_coin
    • First observedroll_dice
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.6/5.0

Scored across 2 tools

Disambiguation5/5

The two tools, roll_dice and flip_coin, are completely distinct in their purpose and behavior. There is no overlap or ambiguity, making it trivial for an agent to select the correct tool.

Naming Consistency5/5

Both tool names follow the same verb_noun pattern (roll_dice, flip_coin), using snake_case and clear action-object structure. This is perfectly consistent and predictable.

Tool Count4/5

With only 2 tools, the server is minimal, but given its explicit 'toy' purpose and narrow domain (random chance events), this count is appropriate and focused. It is slightly thin by general standards but well-scoped for a toy.

Completeness4/5

The tool surface covers the two most common random generators (dice and coin flips). While a generic random number generator or card draw might be expected in a broader utilities server, for a toy server focused on simple chance, these tools are sufficient and leave no obvious dead ends.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Random Number MCP

    zazencodes
    A
    license
    A
    quality
    C
    maintenance
    Production-ready MCP server that provides LLMs with essential random generation abilities, including random integers, floats, choices, shuffling, and cryptographically secure tokens.
    7
    54 PyPI
    50
    MIT

  • Random-Generator

    xiaobenyang-com
    A
    license
    A
    quality
    D
    maintenance
    An encrypted and secure random number generation server that complies with the MCP protocol, suitable for AI applications, LLMS, and other systems that require high-quality random numbers.
    7
    2
    Apache 2.0

  • mcp-tools-server

    RenanMiqueloti
    A
    license
    Not graded
    quality
    D
    maintenance
    A general-purpose MCP server with utility tools including datetime information, safe math calculations, text statistics, JSON extraction, knowledge base search, and HTTP GET requests. It demonstrates server-side MCP implementation and can be connected to Claude Desktop or LangGraph agents.
    MIT

  • mcp-random

    MikeyBeez
    A
    license
    A
    quality
    C
    maintenance
    MCP server providing true randomness capabilities to Claude, enabling cryptographically secure random number generation for games, decision-making, sampling, simulations, and any operation requiring genuine randomness.
    13
    2
    MIT