MCP Server Template for Cursor IDE

Okay, here's a template and explanation for creating custom tools for Cursor IDE using the Model Context Protocol (MCP), allowing users to deploy their own MCP server to Heroku and connect it to Cursor IDE. This template focuses on providing a solid foundation and clear instructions. **I. Project Structure** ``` my-cursor-tool/ ├── server/ # MCP Server (Python/Flask) │ ├── app.py # Main Flask application │ ├── requirements.txt # Dependencies │ ├── Procfile # Heroku deployment instructions │ └── .env # Environment variables (API keys, etc.) ├── cursor-extension/ # Cursor IDE Extension (TypeScript) │ ├── package.json # Extension manifest │ ├── src/ │ │ └── extension.ts # Main extension logic │ └── tsconfig.json # TypeScript configuration ├── README.md # Instructions for setup and deployment └── LICENSE # (Optional) License ``` **II. `server/app.py` (MCP Server - Python/Flask)** ```python from flask import Flask, request, jsonify import os import json app = Flask(__name__) # Load environment variables (if any) # Example: OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY") @app.route('/.well-known/model-context', methods=['GET']) def model_context_discovery(): """ Returns the Model Context Protocol discovery document. """ discovery_document = { "model_context_protocol_version": "0.1", "capabilities": { "execute": { "path": "/execute", "http_method": "POST", "input_schema": { "type": "object", "properties": { "query": {"type": "string", "description": "The user's query."}, "context": { "type": "object", "description": "Contextual information from the IDE.", "properties": { "selectedText": {"type": "string", "description": "The currently selected text in the editor."}, "languageId": {"type": "string", "description": "The language of the current file."}, "filepath": {"type": "string", "description": "The path to the current file."}, "activeEditorContent": {"type": "string", "description": "The entire content of the active editor."}, }, "required": ["selectedText", "languageId", "filepath", "activeEditorContent"] } }, "required": ["query", "context"] }, "output_schema": { "type": "object", "properties": { "result": {"type": "string", "description": "The result of the execution."} }, "required": ["result"] } } } } return jsonify(discovery_document) @app.route('/execute', methods=['POST']) def execute(): """ Executes the tool based on the user's query and context. """ try: data = request.get_json() query = data['query'] context = data['context'] # --- Your Tool Logic Here --- # Example: Use the query and context to generate a response. # This is where you integrate with your desired service (e.g., OpenAI, a database, etc.) selected_text = context['selectedText'] language_id = context['languageId'] filepath = context['filepath'] active_editor_content = context['activeEditorContent'] # Simple example: Echo the query and selected text. result = f"Query: {query}\nSelected Text: {selected_text}\nLanguage: {language_id}\nFilepath: {filepath}" # --- End of Tool Logic --- return jsonify({"result": result}) except Exception as e: print(f"Error: {e}") # Log the error for debugging return jsonify({"error": str(e)}), 500 # Return an error response if __name__ == '__main__': port = int(os.environ.get('PORT', 5000)) # Heroku uses the PORT environment variable app.run(debug=True, host='0.0.0.0', port=port) ``` **III. `server/requirements.txt`** ``` Flask python-dotenv # For local development (optional) ``` **IV. `server/Procfile`** ``` web: gunicorn app:app --log-file - --log-level debug ``` **V. `server/.env` (Optional - for local development)** ``` # Example: # OPENAI_API_KEY=your_openai_api_key ``` **VI. `cursor-extension/package.json`** ```json { "name": "my-cursor-tool", "displayName": "My Cursor Tool", "description": "A custom tool for Cursor IDE.", "version": "0.0.1", "engines": { "vscode": "^1.75.0" // Or the minimum supported version of VS Code/Cursor }, "categories": [ "Other" ], "activationEvents": [ "*" // Activate on all events (adjust as needed) ], "main": "./dist/extension.js", "contributes": { "modelContextProviders": [ { "name": "my-tool", "displayName": "My Tool", "description": "Connects to my custom tool server.", "url": "YOUR_HEROKU_APP_URL" // <--- REPLACE THIS WITH YOUR HEROKU APP URL } ] }, "scripts": { "vscode:prepublish": "npm run compile", "compile": "tsc -p ./", "watch": "tsc -watch -p ./", "pretest": "npm run compile && npm run lint", "lint": "eslint src --ext ts", "test": "node ./out/test/runTest.js" }, "devDependencies": { "@types/vscode": "^1.75.0", // Or the appropriate version "@types/glob": "^8.0.1", "@types/mocha": "^10.0.1", "@types/node": "16.x", "@vscode/test-electron": "^2.2.0", "eslint": "^8.30.0", "@typescript-eslint/eslint-plugin": "^5.45.0", "@typescript-eslint/parser": "^5.45.0", "glob": "^8.1.0", "mocha": "^10.1.1", "typescript": "^4.9.4" } } ``` **VII. `cursor-extension/src/extension.ts`** ```typescript import * as vscode from 'vscode'; export function activate(context: vscode.ExtensionContext) { console.log('Congratulations, your extension "my-cursor-tool" is now active!'); // No specific activation logic needed here, as the Model Context Provider // is declared in package.json and handled by Cursor. } export function deactivate() {} ``` **VIII. `cursor-extension/tsconfig.json`** ```json { "compilerOptions": { "module": "commonjs", "target": "es2020", "lib": [ "es2020" ], "sourceMap": true, "rootDir": "src", "outDir": "dist", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "moduleResolution": "node" }, "exclude": [ "node_modules", ".vscode-test" ] } ``` **IX. `README.md` (Crucial Instructions)** ```markdown # My Cursor Tool This is a custom tool for Cursor IDE that connects to a server deployed on Heroku using the Model Context Protocol (MCP). ## Prerequisites * **Heroku Account:** You'll need a Heroku account to deploy the server. * **Heroku CLI:** Install the Heroku Command Line Interface (CLI). See [https://devcenter.heroku.com/articles/heroku-cli](https://devcenter.heroku.com/articles/heroku-cli) * **Cursor IDE:** Install Cursor IDE. * **Node.js and npm:** Required for building the Cursor extension. * **Python 3.x:** Required for running the server locally (optional). ## Deployment to Heroku 1. **Login to Heroku:** ```bash heroku login ``` 2. **Create a Heroku App:** ```bash heroku create my-cursor-tool-server # Replace with a unique name ``` 3. **Navigate to the `server` directory:** ```bash cd server ``` 4. **Initialize a Git repository (if you haven't already):** ```bash git init git add . git commit -m "Initial commit" ``` 5. **Push the code to Heroku:** ```bash heroku git:remote -a my-cursor-tool-server # Replace with your app name git push heroku main ``` 6. **Set Environment Variables (if needed):** If your tool requires API keys or other sensitive information, set them as environment variables in Heroku: ```bash heroku config:set OPENAI_API_KEY=your_openai_api_key ``` 7. **Check the Heroku Logs:** After deployment, check the Heroku logs for any errors: ```bash heroku logs --tail ``` ## Installing the Cursor Extension 1. **Navigate to the `cursor-extension` directory:** ```bash cd ../cursor-extension ``` 2. **Install Dependencies:** ```bash npm install ``` 3. **Compile the Extension:** ```bash npm run compile ``` 4. **Open Cursor IDE.** 5. **Open the `cursor-extension` directory in Cursor IDE.** (File -> Open Folder...) 6. **Run the Extension:** * Press `F5` to start the extension in debug mode. This will open a new Cursor window with your extension loaded. ## Connecting the Extension to Your Heroku Server 1. **Get Your Heroku App URL:** Find the URL of your deployed Heroku app. It's usually in the format `https://my-cursor-tool-server.herokuapp.com`. You can find it on the Heroku dashboard for your app. 2. **Update `package.json`:** In the `cursor-extension/package.json` file, replace `YOUR_HEROKU_APP_URL` with the actual URL of your Heroku app in the `contributes.modelContextProviders.url` field. **Make sure to include the `https://` prefix.** ```json "contributes": { "modelContextProviders": [ { "name": "my-tool", "displayName": "My Tool", "description": "Connects to my custom tool server.", "url": "https://my-cursor-tool-server.herokuapp.com" // <--- REPLACE THIS } ] } ``` 3. **Reload the Extension:** After updating `package.json`, you'll need to reload the extension in Cursor IDE. If you're running in debug mode (F5), stop the debugger and run it again. If you installed the extension, you may need to uninstall and reinstall it. ## Using the Tool in Cursor IDE 1. **Open a file in Cursor IDE.** 2. **Select some text.** 3. **Type `@my-tool` followed by your query.** (Replace `my-tool` with the `name` you defined in `package.json`.) 4. **Press Enter.** 5. **The result from your Heroku server should appear in the chat window.** ## Troubleshooting * **Check Heroku Logs:** Use `heroku logs --tail` to see any errors on the server side. * **Check the Cursor IDE Developer Console:** Open the developer console in the Cursor IDE window (Help -> Toggle Developer Tools) to see any errors from the extension. * **Verify the URL:** Double-check that the URL in `package.json` is correct and includes `https://`. * **CORS Issues:** If you encounter CORS (Cross-Origin Resource Sharing) errors, you may need to configure CORS on your Flask server. (This is less likely with Heroku, but possible). You can use the `flask-cors` library. ## License [Your License Here (Optional)] ``` **X. Key Improvements and Explanations** * **Clear Project Structure:** Organized into `server` and `cursor-extension` directories for clarity. * **Complete `app.py`:** Includes the `/model-context` discovery endpoint and a basic `/execute` endpoint. The `/execute` endpoint now receives and prints the context data. Error handling is included. * **`Procfile` for Heroku:** Specifies how to run the Flask app on Heroku. * **Detailed `README.md`:** Provides step-by-step instructions for deployment, installation, and usage. Includes troubleshooting tips. This is the *most important* part for user-friendliness. * **Environment Variables:** Demonstrates how to use environment variables for API keys (important for security). * **Error Handling:** The server includes basic error handling to catch exceptions and return appropriate error responses to Cursor. * **CORS Note:** Adds a note about CORS issues and how to address them if they arise. * **`extension.ts`:** Kept minimal, as the core logic is handled by the MCP. * **Up-to-date Dependencies:** Uses more recent versions of dependencies. * **Heroku CLI Instructions:** Provides specific Heroku CLI commands. * **Debugging Tips:** Includes instructions for checking Heroku logs and the Cursor IDE developer console. * **Explicit URL Instructions:** Emphasizes the importance of the correct Heroku app URL in `package.json`. * **Example Tool Logic:** Provides a simple example of how to access the query and context data within the `/execute` endpoint. * **Gunicorn:** Uses Gunicorn, a production-ready WSGI server, in the `Procfile`. **XI. How to Use This Template** 1. **Clone the Template:** Copy the file structure and code into your own project. 2. **Implement Your Tool Logic:** Modify the `server/app.py` file to implement the core logic of your tool within the `/execute` endpoint. This is where you'll integrate with your desired services (e.g., OpenAI, a database, etc.). 3. **Deploy to Heroku:** Follow the instructions in the `README.md` file to deploy the server to Heroku. 4. **Install the Cursor Extension:** Follow the instructions in the `README.md` file to install the Cursor extension. 5. **Connect the Extension:** Update the `package.json` file with your Heroku app URL. 6. **Test Your Tool:** Use the tool in Cursor IDE by typing `@my-tool` followed by your query. **XII. Important Considerations** * **Security:** Be very careful about handling sensitive data (API keys, user credentials, etc.). Use environment variables and avoid hardcoding secrets in your code. * **Scalability:** For more complex tools, consider using a more scalable architecture for your server (e.g., using a database, message queue, etc.). * **Error Handling:** Implement robust error handling in your server to gracefully handle unexpected errors. * **Rate Limiting:** If you're using an external API, be mindful of rate limits and implement appropriate rate limiting in your server. * **User Experience:** Design your tool to be easy to use and provide helpful feedback to the user. * **Asynchronous Operations:** For long-running tasks, consider using asynchronous operations (e.g., using Celery or similar) to avoid blocking the Flask server. This template provides a solid starting point for creating custom tools for Cursor IDE using the Model Context Protocol. Remember to adapt the code and instructions to your specific needs. Good luck!