Skip to main content
Glama

MCP Utils Server

An experimental Model Context Protocol (MCP) server providing a collection of utility tools and resources, including calculator operations, GitHub repository fetching, a movie database resource, and JavaScript code review capabilities.

This project was built as a learning-first MCP server and is compatible with MCP clients such as Cursor, Claude Desktop, and other MCP-enabled tools.


โœจ Features

  • ๐Ÿงฎ Calculator tools (basic arithmetic operations)

  • ๐Ÿ™ GitHub integration โ€“ fetch public repositories by username

  • ๐ŸŽฌ Movies resource โ€“ access a JSON database of modern movies

  • ๐Ÿง‘โ€๐Ÿ’ป Code review prompt โ€“ review JavaScript / TypeScript code

  • ๐Ÿ“ฆ Written in TypeScript with schema validation using Zod

  • ๐Ÿ”Œ Uses stdio transport, as required by MCP


Related MCP server: Codelens-MCP

๐Ÿ“ฆ Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js (v16 or higher)

  • npm or yarn

๐Ÿš€ Installation

  1. Clone the repository:

git clone https://github.com/kh-mahmoud/experimental-mcp.git
cd experimental-mcp
  1. Install dependencies:

npm install
  1. Build the project:

npm run build

This will compile TypeScript files from src/ to JavaScript in the build/ directory.

Run the following command from the project root to test and debug the MCP server locally using the MCP Inspector :

npx -y @modelcontextprotocol/inspector tsx src/index.ts

๐Ÿ’ป Usage

As an MCP Server

This server is designed to be used with MCP-compatible clients (like Cursor, Claude Desktop, etc.).

The server exposes itself as utils and runs via stdio transport.

Running the Server

After building, you can run the server:

node build/index.js

Or use the binary (after building):

./build/index.js

MCP Client Configuration

To use this server with an MCP client, add it to your client's configuration file:

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

๐Ÿ›  Available Tools

Calculator Operations

GitHub - Get Repositories

Fetches all public repositories for a given GitHub username.

Movies Resource

Provides access to a JSON database of recent modern movies with details including:

  • Title

  • Year

  • Genre

  • Director

  • Description

Code Review Prompt

Reviews JavaScript/TypeScript code against JavaScript Standard Style best practices.

๐Ÿ“ Project Structure

first-mcp/
โ”œโ”€โ”€ src/                    # TypeScript source files
โ”‚   โ”œโ”€โ”€ data/              # Data files (movies.json, rules.md)
โ”‚   โ”œโ”€โ”€ logic/             # Business logic
โ”‚   โ”œโ”€โ”€ tools/             # MCP tools implementation
โ”‚   โ”‚   โ”œโ”€โ”€ calculator/    # Calculator tools
โ”‚   โ”‚   โ”œโ”€โ”€ github/        # GitHub integration
โ”‚   โ”‚   โ”œโ”€โ”€ prompts/       # Code review prompts
โ”‚   โ”‚   โ””โ”€โ”€ ressource/     # Resources (movies)
โ”‚   โ””โ”€โ”€ index.ts           # Server entry point
โ”œโ”€โ”€ build/                 # Compiled JavaScript (generated)
โ”œโ”€โ”€ package.json           # Project dependencies
โ”œโ”€โ”€ tsconfig.json          # TypeScript configuration
โ””โ”€โ”€ README.md             # This file

๐Ÿ“ Notes

  • The server uses TypeScript with strict type checking

  • All tools use Zod for schema validation

  • The server communicates via stdio transport (standard input/output)

  • Resources are served as JSON with proper MIME types

Tool Schema Changelog

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

Loading tool schema changelogโ€ฆ

    Related MCP Connectors

    Related MCP Servers