mcptest

# MCP Task Scheduler ## Overview This project is a sample task scheduling application that utilizes the Model Context Protocol (MCP). When users input tasks in natural language, the AI (Google Gemini) breaks them down into subtasks, outputs the plan to Google Docs, and finds available time slots in Google Calendar to schedule the tasks. It adopts a client-server model, where the server functions as the MCP server, and the client operates via a CLI (Command Line Interface). ## Features - Natural language task input - Automatic breakdown into subtasks and time estimation using the Gemini API - Automatic generation of a task list in Google Docs - Automatic scheduling based on available time in Google Calendar (Earliest-Fit algorithm) - Buffer time settings between tasks - Interactive operation via CLI (with a step to confirm subtasks) - Secure authentication using Google OAuth 2.0 ## Technical Stack - Node.js - TypeScript - Model Context Protocol SDK (`@modelcontextprotocol/sdk`) - Google Gemini API (`@google/generative-ai`) - Google Docs API (`googleapis`) - Google Calendar API (`googleapis`) - Google Authentication Library (`google-auth-library`, `@google-cloud/local-auth`) - Zod (schema validation) - Dotenv (environment variable management) ## Prerequisites - Node.js (v18 or later recommended) - npm (included with Node.js) - Google Cloud Platform project - The following APIs enabled in your Google Cloud project: - Google Docs API - Google Calendar API - OAuth 2.0 Client ID (Type: **Desktop App**) - Create this in the Google Cloud Console under "APIs & Services" -> "Credentials". - Download the JSON file for the created credentials. - Gemini API Key - Obtain this from [Google AI Studio](https://aistudio.google.com/app/apikey) or similar. ## Setup Instructions 1. **Clone the repository:** ```bash git clone <repositoryURL> cd <repositoryName> ``` 2. **Install dependencies:** ```bash npm install ``` 3. **Set up environment variables:** * Create a file named `.env` in the root directory of the project. * Place the JSON file of the OAuth 2.0 Client ID downloaded from Google Cloud Console in the root directory of the project. The filename can be anything, but you will specify it later in the `.env` file. * Write the following content in the `.env` file, setting your obtained Gemini API key and the **filename** of the placed client secret file. ```dotenv # Gemini API Key GEMINI_API_KEY=YOUR_GEMINI_API_KEY # Path to your Google Cloud OAuth 2.0 Client ID file (relative to project root) # Replace 'client_secret_xxxxxxxx.apps.googleusercontent.com.json' # with the actual filename of the JSON key file you downloaded and placed in the root. GOOGLE_CREDENTIALS_PATH=client_secret_xxxxxxxx.apps.googleusercontent.com.json ``` * **Note:** The `.env` file and the client secret JSON file contain sensitive information. Ensure that `.gitignore` includes `.env` and `*.json` (or specific filename patterns) to avoid committing them to the Git repository. 4. **Build:** * Compile TypeScript code to JavaScript. ```bash npm run build ``` * This will generate the necessary files in the `dist` directory. 5. **Initial Google Authentication:** * When you run the client for the first time, an authentication flow will start asking for permissions to access Google Docs and Calendar. * The console of the server (which runs internally in the client) will display an authentication URL. Open this in your browser, log in with your Google account, and grant access. * **Important:** Since the app has not been reviewed by Google, you may see a warning about "unverified app." To grant access, you need to add your Google account to the "Test Users" section in the Google Cloud Console under "OAuth Consent Screen." (Refer to the [Google Cloud documentation](https://developers.google.com/identity/protocols/oauth2/web-server#handlingresponse) for details.) * Upon successful authentication, an access token (including a refresh token) will be saved as `token.json` in the project root, which will be used for subsequent runs. * If you change the scopes, you will need to delete `token.json` and run it again. ## Usage 1. **Start the server (in the background):** * Run the following command to start the MCP server, which will wait for connections from the client. ```bash npm run start ``` * **Note:** The server must be running before you execute the client. 2. **Run the client:** * Open another terminal and execute the command in the following format. ```bash npm run client "<description of the task to plan/schedule>" ``` **Example:** ```bash npm run client "Prepare for next week's team meeting" ``` 3. **Execution flow:** * The client connects to the server and calls the `plan_task` tool. * The server calls the Gemini API to generate a list of subtasks. * The client displays the generated subtask list in the console. * The console will prompt `Do you want to schedule these tasks? (Y/n):` for confirmation. * Entering `y` or `Y` (or pressing Enter) will proceed to the scheduling process. * Entering `n` or `N` will cancel the process and exit. * Once the schedule is selected, the client will call the `schedule_tasks` tool. * The server will create the plan in Google Docs and schedule the subtasks in Google Calendar. * The client will display the final results (Google Docs URL, summary of scheduling results) in the console. 4. **Check results:** * Access the Google Docs URL output in the console to review the plan. * Check your Google Calendar to confirm that the tasks have been scheduled. ## Configuration Items (Optional) The following items can be modified directly in the source code as needed. - **Scheduling settings (`src/server.ts`):** - `SCHEDULING_START_OFFSET_DAYS`: How many days later to start searching for schedules. - `SCHEDULING_WINDOW_DAYS`: The range of days to search for available time slots. - `SCHEDULING_WORK_DAY_START_HOUR` / `SCHEDULING_WORK_DAY_END_HOUR`: The working hours to be scheduled. - `SCHEDULING_BUFFER_MINUTES`: The buffer time to insert between tasks. - **Gemini model (`src/server.ts`):** - The `model` name in `geminiModel = genAI.getGenerativeModel({ model: "..." })`. - **Google API scopes (`src/auth.ts`):** - You can add or modify the necessary permissions in the `SCOPES` array (deleting `token.json` is required after changes). ## Notes - **Management of API keys and credential files:** Never expose the `.env` file and the client secret JSON file downloaded from Google Cloud. Ensure they are properly excluded in `.gitignore`. - **Google Authentication:** The initial authentication flow and test user registration are required. - **Error handling:** There may be API rate limits or unexpected errors. Check the error messages and retry after some time if necessary. - **Progress notifications:** Currently, real-time progress notification functionality from the server to the client is not implemented (the code is commented out).