Skip to main content
Glama
Sign In
teaching-mcp-server

teaching-mcp-server

by DouglasGBailey
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Teaching MCP Server

A small, local Model Context Protocol (MCP) server built for teaching purposes. It demonstrates five of the most common categories of things MCP servers are used for, with heavily commented, readable TypeScript source.

The five capabilities

#

Capability

Tools

1

Local filesystem access

read_file, write_file, list_directory

2

Persistent structured storage (CRUD)

add_note, list_notes, get_note, delete_note

3

Outbound HTTP / calling external APIs

fetch_url

4

Local system introspection

get_system_info

5

Deterministic text processing

analyze_text, transform_text

See FUNCTIONAL_SPEC.md for what each tool does and why, TECHNICAL_SPEC.md for how it's built, and HOW_IT_WORKS.md for a guided walkthrough of MCP itself using this project as the example.

Related MCP server: Atlas MCP Server

Quick start

npm install
npm run build
npm start

The server speaks MCP over stdio, so running npm start directly in a terminal will just sit there waiting for a client to talk to it — that's expected. It's meant to be launched by an MCP client such as Claude Code or Claude Desktop.

Connect it to Claude Code

Add it as a local MCP server (from this project directory):

claude mcp add teaching-mcp-server -- node dist/index.js

Connect it to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "teaching-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/claude-mcp-2/dist/index.js"]
    }
  }
}

Restart Claude Desktop, then look for the tools icon to confirm the server connected and its 11 tools are listed.

Project layout

claude-mcp-2/
├── src/
│   ├── index.ts            # Entry point: creates the server, registers tools, connects stdio
│   ├── paths.ts             # Filesystem sandboxing helper (workspace path validation)
│   ├── notesStore.ts        # JSON-file-backed persistence for the notes tools
│   └── tools/
│       ├── filesystem.ts    # Capability 1
│       ├── notes.ts         # Capability 2
│       ├── web.ts           # Capability 3
│       ├── system.ts        # Capability 4
│       └── text.ts          # Capability 5
├── workspace/                # Sandbox root for read_file / write_file / list_directory
├── data/                     # notes.json lives here
├── HOW_IT_WORKS.md
├── FUNCTIONAL_SPEC.md
└── TECHNICAL_SPEC.md

Try it

Once connected in Claude Code or Claude Desktop, try asking:

  • "List the files in your workspace, then read welcome.txt."

  • "Add a note titled 'Groceries' with a short shopping list, then show me all my notes."

  • "Fetch https://example.com and summarize what's there."

  • "What's the CPU and memory usage on this machine?"

  • "Count the words and get a SHA-256 hash of this paragraph: ..."

Available Tools

11 tools
add_noteAdd a noteA

Create a new persisted note with a title and body. Returns the generated note id, which is needed later to fetch or delete it.

Inputs: body (required), title (required).

analyze_textAnalyze textA

Compute exact statistics for a block of text: character count, word count, line count, sentence count (approximate), and a SHA-256 hash. Useful whenever an exact count or checksum matters.

Inputs: text (required).

delete_noteDelete a noteB

Permanently delete a note by its id.

Inputs: id (required).

fetch_urlFetch a URLA

Fetch the contents of a public http(s) URL and return the response body as text (truncated to a safe length). Useful for reading web pages, JSON APIs, or other public HTTP resources. Only http and https URLs are allowed.

Inputs: url (required), body, method.

get_noteGet a note by idA

Fetch the full title and body of one note by its id.

Inputs: id (required).

get_system_infoGet local system informationA

Report information about the machine running this MCP server: operating system, CPU, memory, uptime, and current local time. Useful for diagnostics or environment-aware suggestions.

Inputs: no named parameters.

list_directoryList a workspace directoryA

List the files and subdirectories inside a directory within the server's sandboxed 'workspace'. Omit 'path' to list the workspace root.

Inputs: path.

list_notesList all notesA

List every stored note (id, title, and timestamps), most recently updated first. Use get_note to fetch a note's full body.

Inputs: no named parameters.

read_fileRead a workspace fileA

Read the full text contents of a file inside the server's sandboxed 'workspace' directory. Provide a path relative to the workspace root (e.g. 'welcome.txt' or 'notes/todo.txt').

Inputs: path (required).

transform_textTransform text caseA

Deterministically transform text into a given case style: uppercase, lowercase, title_case, snake_case, or kebab_case.

Inputs: text (required), style (required).

write_fileWrite a workspace fileA

Create or overwrite a text file inside the server's sandboxed 'workspace' directory. Parent directories are created automatically.

Inputs: path (required), content (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.9/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a clearly distinct resource or operation: file sandbox operations, note CRUD, URL fetching, system info, and text analysis/transformation. The only potential overlap is between add_note/write_file and analyze_text/transform_text, but the descriptions sharply separate their purposes. An agent should have no trouble selecting the right tool.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern: read_file, write_file, list_directory, add_note, list_notes, get_note, delete_note, fetch_url, get_system_info, analyze_text, transform_text. The convention is predictable throughout the set.

    Tool Count5/5

    With 11 tools, the server is well-scoped for a teaching/demo MCP server that showcases several capabilities. Each tool has a clear individual purpose and the count stays comfortably within a reasonable range without feeling bloated.

    Completeness4/5

    The surface covers file read/write/list, note create/list/get/delete, URL fetch, system info, and text analysis/transformation. Minor gaps exist: there is no file deletion/removal tool and no note update tool, though agents can work around these by overwriting files or deleting and recreating notes.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers