42 MCP Server

English | 日本語

42 MCP Server is a server that exposes 42's intranet API through the Model Context Protocol (MCP). This enables LLM (Large Language Model) agents to safely and standardized access to 42's rich data (user information, projects, campus information, etc.).

Overview

This server abstracts requests to the 42 API and provides them in the form of resources and tools defined by MCP. It supports two transport modes, Stdio and HTTP, making it compatible with a wide range of clients from CLI tools to modern IDE extensions.

Features

• Dual Transport: Supports both Stdio and HTTP.
• 42 API Integration: Provides information about 42 users, projects, campuses, and more.
• Tools: Equipped with many useful tools such as user search and Cursus level retrieval.

Prerequisites

• Node.js (v20.x or later)
• npm
• 42 API client ID and secret

Setup

1. Clone the repository:

   git clone https://github.com/smizuoch/42-mcp-server.git
   cd 42-mcp-server

2. Install dependencies:

   npm install

3. Get 42 API credentials: You need to create an OAuth application on the 42 intranet to get the client ID and secret.

   1. Access 42 OAuth Applications
   2. Log in with your 42 account
   3. Fill in the application details:
      • Name: Enter a name for your application (e.g., "42 MCP Server")
      • Redirect URI: Enter http://localhost:8080 (or any localhost URL)
      • Scopes: Select appropriate scopes (e.g., public for basic access)
   4. Click "Submit" to create the application
   5. Copy the generated Application ID and Secret

4. Set up environment variables: Copy .env.example to create a .env file and fill in your 42 API credentials.

   cp .env.example .env

   Contents of .env file:

   42_CLIENT_ID=YOUR_42_CLIENT_ID
   42_CLIENT_SECRET=YOUR_42_CLIENT_SECRET
   

   Replace YOUR_42_CLIENT_ID with the Application ID and YOUR_42_CLIENT_SECRET with the Secret from step 3.

Usage

Development Mode

• Stdio Mode: Communicates with MCP clients using standard input/output.

  npm run dev

• HTTP Mode: Starts an HTTP server to communicate with MCP clients. Useful for VSCode extensions and similar tools.

  npm run dev:http

Production

1. Build TypeScript:

   npm run build

2. Start HTTP server:

   npm run start

   The server will start at http://127.0.0.1:8042.

VSCode Integration

1. Start the server in HTTP mode:

   npm run dev:http

   You'll see logs like this in the terminal:

   MCP HTTP server ready on port 8042
   MCP endpoint: http://127.0.0.1:8042/
   Health check: http://127.0.0.1:8042/health
   
   VSCode Configuration (.vscode/mcp.json):
   {
     "servers": {
       "42-api": {
         "url": "http://127.0.0.1:8042/"
       }
     }
   }
   

2. Create VSCode configuration file: Create a file named .vscode/mcp.json in the project root and paste the content shown in the logs above.

   .vscode/mcp.json:

   {
     "servers": {
       "42-api": {
         "url": "http://127.0.0.1:8042/"
       }
     }
   }

3. After reloading VSCode, the extension will recognize the server and you can call resources and tools with prefixes like @42-api.

Provided MCP Features

Resources

URI	Description
42://user/{id}	User profile for the specified ID
42://me	Profile of the currently authenticated user
42://campus	List of all campuses
42://attachments	List of all attachments
42://attachments/{id}	Attachments for the specified project
42://projects	List of all projects
42://project/{id}	Project details for the specified ID
42://me/projects	List of projects for the authenticated user
42://accreditations	List of all accreditations
42://accreditation/{id}	Accreditation details for the specified ID

Tools

Tool Name	Description
searchUsers	Search for users by login name.
getCursusLevel	Get a user's level in a specific Cursus.
getUserProjects	Get a list of user's projects.
getCoalition	Get Coalition information for a user.
getCampusUsers	Get campus-user associations by campus ID or user ID.
getBalances	Get balance information (requires specific role).
getClusters	Get cluster information (requires specific role).
getLocations	Get user login status (seat information).
getAttachments	Get a list of attachments for projects or project sessions.
getAttachment	Get detailed information (such as PDF URLs) for a specific attachment.
getProjects	Get a list of projects (with optional Cursus and filter specifications).
getProject	Get detailed information for a specific project.
getMyProjects	Get a list of projects for the authenticated user.
getAccreditations	Get a list of accreditations with optional filtering by user, cursus, validation status.
getAccreditation	Get detailed information for a specific accreditation.

Tech Stack

• TypeScript
• Node.js
• Express
• @modelcontextprotocol/sdk
• Zod