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

---

📦 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

2. Install dependencies:

npm install

3. 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

🔗 Related Links

• Model Context Protocol
• MCP SDK Documentation