Skip to main content
Glama
My Learning MCP Server

My Learning MCP Server

๐Ÿค– 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.

Inputs: a (required), b (required), operation (required).

get_weatherA

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

Inputs: city (required), unit.

Tool Schema Changelog

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

Loading tool schema changelogโ€ฆ

    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 recent community issues

    Related MCP Connectors

    Related MCP Servers

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