# 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

---

## 📦 Prerequisites

Before you begin, ensure you have the following installed:

- **Node.js** (v16 or higher)
- **npm** or **yarn**

## 🚀 Installation

1. Clone the repository:
```bash
git clone https://github.com/kh-mahmoud/experimental-mcp.git
cd experimental-mcp
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
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** :

```bash
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:

```bash
node build/index.js
```

Or use the binary (after building):

```bash
./build/index.js
```

### MCP Client Configuration

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

```json
{
  "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](https://modelcontextprotocol.io/)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)