Skip to main content
Glama
sushobhitrajan

My Learning MCP Server

by sushobhitrajan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

🤖 My Learning MCP Server

A hands-on MCP (Model Context Protocol) server built with TypeScript to learn the three core MCP primitives: Tools, Resources, and Prompts.

📚 What is MCP?

The Model Context Protocol is an open standard by Anthropic that lets AI models (like Claude) connect to external data sources, APIs, and custom logic in a standardized way.

graph LR
    subgraph Hosts["AI Hosts"]
        A["Claude Desktop"]
        B["MCP Inspector"]
        C["Gemini LLM Client"]
    end

    subgraph Server["🟢 MCP Server  —  this project"]
        E["src/index.ts"]
        subgraph T["🔧 Tools"]
            F["calculator"]
            G["get_weather"]
        end
        subgraph R["📄 Resources"]
            H["notes://all · 1 · 2 · 3"]
        end
        subgraph P["💬 Prompts"]
            I["code-review · explain-concept"]
        end
        E --> F & G & H & I
    end

    A & B & C -->|"MCP Protocol / stdio"| E

    classDef host fill:#3b82f6,stroke:#1d4ed8,color:#fff
    classDef server fill:#22c55e,stroke:#15803d,color:#fff
    classDef prim fill:#f0fdf4,stroke:#16a34a,color:#166534
    class A,B,C host
    class E server
    class F,G,H,I prim

Related MCP server: simple_mcp

🏗️ Project Structure

my-mcp-server/
├── src/
│   ├── index.ts              ← Main MCP server entry point
│   ├── client/
│   │   └── index.ts          ← 🤖 Gemini LLM client
│   ├── tools/
│   │   ├── calculator.ts     ← 🔧 Calculator tool
│   │   └── weather.ts        ← 🔧 Weather lookup tool
│   ├── resources/
│   │   └── notes.ts          ← 📄 Notes resource
│   └── prompts/
│       └── templates.ts      ← 💬 Prompt templates
├── spec/
│   ├── README.md             ← Spec index
│   ├── 01-architecture/      ← Server architecture design
│   │   └── why-mcp.md        ← "N × M" problem breakdown
│   └── 02-llm-client/        ← LLM client design
├── .env                      ← API keys (gitignored)
├── package.json
├── tsconfig.json
└── README.md

🧩 Core MCP Primitives

Primitive

Purpose

Example

🔧 Tools

Actions the AI can execute

Calculate math, fetch weather

📄 Resources

Data the AI can read

Notes, files, DB records

💬 Prompts

Reusable message templates

Code review, explain concept

🚀 Getting Started

1. Install dependencies

npm install

2. Set up your API key (required for LLM client)

cp .env.example .env

Then open .env and add your Gemini API key:

GEMINI_API_KEY=your_key_here

Get a free key at aistudio.google.com/app/apikeys. See spec/02-llm-client/design.md for detailed setup steps.

⚠️ The MCP Inspector and server work without the key. Only npm run client needs it.

3. Run in dev mode (with hot reload)

npm run dev

4. Open the MCP Inspector (visual debugger in the browser)

npm run inspector

This opens a web UI where you can:

  • Call tools interactively

  • Browse and read resources

  • Try out prompt templates

5. Run the Gemini LLM client (requires API key from step 2)

npm run client

Chat in plain English — Gemini will automatically call tools as needed.

6. Build for production

npm run build

🔧 Tools

Tools let the AI execute actions (like making an API call or calculating math).

How to use:

  • In MCP Inspector (npm run inspector): Go to the Tools tab, select a tool, enter the JSON arguments, and click "Run Tool".

  • In Gemini Client (npm run client): Ask natural language questions like "What is 25 x 4?" or "What's the weather in Tokyo?" Gemini will automatically call the tool for you.

calculator

Perform basic arithmetic operations.

Input:

{
  "operation": "add" | "subtract" | "multiply" | "divide",
  "a": number,
  "b": number
}

Example: { "operation": "multiply", "a": 12, "b": 7 } → 12 multiply 7 = 84

get_weather

Get current weather for a city (uses mock data for learning).

Input:

{
  "city": "London",
  "unit": "celsius" | "fahrenheit"
}

Example response:

{
  "city": "London",
  "temperature": "12°C",
  "humidity": "80%",
  "condition": "Cloudy",
  "timestamp": "2025-01-01T10:00:00.000Z"
}

📄 Resources

Resources provide read-only data (like a file or database) for the AI to read.

How to use:

  • In MCP Inspector (npm run inspector): Go to the Resources tab and click "List Resources" to see all available notes. Click on a specific URI (like notes://1) and click "Read Resource" to see its contents.

  • In Gemini Client: (Coming soon - currently the client only supports Tools, not Resources).

Resources are accessed via URI:

URI

Description

notes://all

Summary list of all notes

notes://1

Note #1: "What is MCP?"

notes://2

Note #2: "MCP Transport Types"

notes://3

Note #3: "Why use Zod for validation?"

💬 Prompts

Prompts are reusable templates (like slash commands) that generate structured instructions for an LLM.

How to use:

  • In MCP Inspector (npm run inspector): Go to the Prompts tab, select code-review or explain-concept, fill out the required arguments (e.g., language: "TypeScript"), and click "Get Prompt". It returns a highly detailed, ready-to-use prompt template.

  • In Claude Desktop: These appear as slash commands. You type /code-review and it prompts you for the arguments.

code-review

Generates a structured code review prompt.

Argument

Required

Values

language

✅

TypeScript, Python, Go, etc.

focus

❌

security | performance | readability | all

explain-concept

Explains a technical concept at a chosen level.

Argument

Required

Values

concept

✅

e.g. "MCP Resources", "async/await"

level

❌

beginner | intermediate | expert

🖥️ Connect to Claude Desktop

Add to your Claude Desktop config file:

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

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/workspace/Personal/my-mcp-server/dist/index.js"]
    }
  }
}

Then run npm run build and restart Claude Desktop.

📖 Key Learnings

  1. stdio transport — the server communicates via stdin/stdout; always log to stderr

  2. Always validate inputs — use Zod's safeParse to catch bad data before it crashes your server

  3. Three primitives — Tools (do), Resources (read), Prompts (template)

  4. McpError — throw typed errors so the client receives structured error responses

  5. Capabilities — declare what your server supports in the Server constructor

📚 Further Reading

Available Tools

2 tools
calculatorA

Perform basic arithmetic operations: add, subtract, multiply, or divide two numbers.

ParametersJSON Schema
NameRequiredDescriptionDefault
aYesThe first number
bYesThe second number
operationYesThe arithmetic operation to perform

TDQS

A3.8/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 clearly describes the core behavior (performs the selected arithmetic operation) but omits edge cases such as division by zero, error handling, or return type. For a pure computation tool, this is acceptable but not deeply transparent.

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, tightly written sentence that front-loads the main verb and resource, then lists the operations. No filler words or unnecessary repetition; every word earns its place.

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, stateless calculator with fully documented parameters, the description is sufficient for an agent to select and invoke it correctly. The absent output schema is not a gap here since the return value (the arithmetic result) is obvious, though the description does not mention division-by-zero behavior.

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 provides 100% coverage for all parameters, including descriptions for a, b, and operation. The tool description merely restates the operation names without adding meaning beyond the schema. 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 states a precise verb ('perform') with a resource ('basic arithmetic operations'), and enumerates the exact operations ('add, subtract, multiply, or divide'). It is unambiguous and clearly distinct from the only sibling tool, get_weather, making the tool's purpose immediately apparent.

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 when to use the tool—whenever basic arithmetic on two numbers is needed—but it does not explicitly state usage context or exclusions. Since the only sibling is get_weather, no alternative routing is needed, but there is no explicit 'when to use' guidance beyond the obvious purpose.

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

get_weatherA

Get the current weather for a city. Returns temperature, humidity, and conditions.

ParametersJSON Schema
NameRequiredDescriptionDefault
cityYesName of the city to get weather for
unitNoTemperature unit (default: celsius)

TDQS

A4/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 behavioral burden and does disclose the return payload and that the data is current. However, it does not mention behavior for invalid or ambiguous city names, data freshness, or the default unit behavior beyond what the schema already says.

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 filler; the core action, target, and return values are all front-loaded. Every clause earns its place.

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 two-parameter read-only tool, the combination of description and schema is largely sufficient: required city, optional unit, and the returned fields are all covered. Missing only minor operational considerations such as error handling, which is acceptable for this level of complexity.

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 input schema already fully documents city and unit, including the default temperature unit. The description adds no parameter-level detail beyond what the schema provides, which meets the baseline but does not exceed it.

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 uses a specific verb ('get'), a clear resource ('current weather'), and a target ('a city'), and explicitly lists the returned data (temperature, humidity, conditions). This makes it easily distinguishable from the only sibling tool, calculator.

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?

The phrase 'current weather for a city' clearly signals the intended use case: when real-time weather data is needed. There are no similar sibling tools that require exclusion, though no explicit when-not-to-use guidance is 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 observedcalculator
    • First observedget_weather
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

Calculator and get_weather are completely unrelated and clearly distinguishable. There is no possibility of confusion between arithmetic operations and weather retrieval.

Naming Consistency3/5

The names use mixed conventions: 'calculator' is a noun while 'get_weather' follows a verb_noun pattern. Both are readable, but the naming style is not consistent across the set.

Tool Count2/5

With only two tools, the server feels very thin, especially for a vaguely named 'Learning MCP Server.' The tools are also unrelated, making the small count feel arbitrary rather than focused.

Completeness2/5

The domain is unclear, so it is difficult to define full coverage. Calculator covers basic arithmetic but no advanced operations, and weather only returns current conditions without forecast or location management, leaving notable gaps.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-toy

    xiangshiyin
    A
    license
    B
    quality
    C
    maintenance
    A toy MCP server for exploring Model Context Protocol capabilities, including resources, tools, and prompts.
    1
    Apache 2.0