# Local Hugging Face MCP Server

A production-ready local MCP (Model Context Protocol) server built with Node.js (ES Modules) that can be connected to Agent Studio via its MCP Servers feature.

## Features

- Exposes multiple tools to Agent Studio:
  - **Calculator**: Performs basic arithmetic operations
  - **Search**: Returns mocked search results (easy to replace with real search)
  - **Chat**: Simple greeting response
  - **Hugging Face**: Interfaces with Hugging Face Inference API for text generation
- Secure: Optional API token authentication
- Environment configurable
- Health check endpoint
- Comprehensive error handling
- Logging of requests and tool invocations
- Built with the latest official `@modelcontextprotocol/sdk`

## Installation

1. Clone or download this repository
2. Install dependencies:

```bash
npm install
```

## Environment Variables

Create a `.env` file in the root directory with the following variables:

```env
PORT=8000
ACCESS_TOKEN=my-secret-token
HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

- `PORT`: The port the server will listen on (default: 8000)
- `ACCESS_TOKEN`: Optional. If set, requires `Authorization: Bearer <token>` header for MCP endpoint. If empty or not set, allows anonymous access.
- `HF_TOKEN`: Your Hugging Face Inference API token (required for the Hugging Face tool)

### Getting a Hugging Face Token

1. Go to [Hugging Face Settings](https://huggingface.co/settings/tokens)
2. Create a new token with "Read" access (for inference API)
3. Copy the token and set it as `HF_TOKEN` in your `.env` file

## Usage

### Starting the Server

#### Production
```bash
npm start
```

#### Development (with auto-restart)
```bash
npm run dev
```

The server will start at `http://localhost:8000`.

### Endpoints

- `GET /` - Returns "MCP Server Running"
- `GET /health` - Returns `{ "status": "ok" }`
- `POST /mcp` - MCP endpoint for Agent Studio (requires authentication if `ACCESS_TOKEN` is set)

## Connecting to Agent Studio

1. Open Agent Studio
2. Navigate to **Settings** → **MCP Servers**
3. Click "Add New Server"
4. Fill in the form:
   - **Name**: Local MCP
   - **Server URL**: `http://localhost:8000/mcp`
   - **Access Token**: `my-secret-token` (if you set `ACCESS_TOKEN` in `.env`; leave blank if not set)
5. Save the connection

Agent Studio will now be able to discover and use the tools exposed by this MCP server.

## Available Tools

### Calculator
Performs basic arithmetic operations.

**Input:**
```json
{
  "a": number,
  "b": number,
  "operation": "add" | "subtract" | "multiply" | "divide"
}
```

**Output:** `Result = <result>`

**Errors:** Throws an error for division by zero.

### Search
Returns mocked search results (replace with real search implementation).

**Input:**
```json
{
  "query": string
}
```

**Output:**
```json
{
  "results": [
    {
      "title": string,
      "url": string,
      "snippet": string
    }
  ]
}
```

### Chat
Simple greeting tool.

**Input:**
```json
{
  "message": string
}
```

**Output:** `Hello from MCP`

### Hugging Face
Interfaces with Hugging Face Inference API for text generation.

**Input:**
```json
{
  "model": string,  // e.g., "gpt2"
  "prompt": string
}
```

**Output:** Generated text string from the model.

**Errors:**
- `HF_TOKEN is not set in environment variables` - Missing Hugging Face token
- `Invalid Hugging Face token` - 401 from HF API
- `Model not found: <model>` - 404 from HF API
- `Rate limit exceeded` - 429 from HF API
- `Request to Hugging Face API timed out` - Timeout after 10 seconds
- `Hugging Face API error: <status> <message>` - Other HTTP errors
- `Unexpected error: <message>` - Other unexpected errors

## Extending with Additional Tools

To add a new tool:

1. Create a new file in the `tools/` directory (e.g., `mytool.js`)
2. Export a handler function and a Zod schema:
   ```javascript
   import { z } from 'zod';

   export const mytoolTool = async (input) => {
     // Your implementation
     return result;
   };

   const mytoolSchema = z.object({
     // Define your input schema
   });

   export { mytoolSchema };
   ```
3. Open `routes/mcp.js` and import the tool:
   ```javascript
   import { mytoolTool } from '../tools/mytool.js';
   import { mytoolSchema } from '../tools/mytool.js';
   ```
4. Inside the `createMcpServer` function, register the tool:
   ```javascript
   server.registerTool(
     'mytool',
     {
       description: 'Description of your tool',
       inputSchema: mytoolSchema
     },
     mytoolTool
   );
   ```
5. Restart the server.

## Project Structure

```
my-mcp-server/
│
├── package.json
├── server.js
├── .env
├── README.md
│
├── tools/
│   ├── calculator.js
│   ├── search.js
│   ├── chat.js
│   └── huggingface.js
│
├── routes/
│   └── mcp.js
│
├── middleware/
│   └── auth.js
│
└── utils/
    └── logger.js
```

## Notes

- The server uses ES modules (`type": "module"` in package.json)
- The MCP server uses the official `@modelcontextprotocol/sdk` for HTTP transport
- Error handling is centralized: invalid requests return 400, auth errors return 401, and internal errors return 500 with a JSON error response
- The Hugging Face tool includes timeout and error handling for common API issues
- Logging is done via console with timestamps

## License

MIT