# Data Engineering Tutor MCP Server

This repo contains a simple Model Context Protocol (MCP) server built with Node.js and TypeScript. It acts as a "Data Engineering Tutor," providing personalized updates about Data Engineering concepts, patterns, and technologies to a connected AI client.

This server demonstrates key MCP concepts: defining **Resources**, **Tools**, and **Prompts** to create a stateful, interactive agent helper.

## Prerequisites

- Node.js (v18 or later recommended)
- `npm` (or your preferred Node.js package manager like `yarn` or `pnpm`)
- An AI client capable of connecting to an MCP server (e.g., Cursor, Claude desktop app)
- An [OpenRouter API Key](https://openrouter.ai/) (for fetching live Data Engineering updates via Perplexity)

## Setup

1.  **Clone the Repository:**

    ```bash
    # If you haven't already
    # git clone <repository-url>
    # cd <repository-directory>
    ```

2.  **Install Dependencies:**

    ```bash
    npm install
    ```

3.  **Prepare API Key:** The `de_tutor_get_updates` tool requires an OpenRouter API key.

    - Obtain your key from [OpenRouter](https://openrouter.ai/).
    - Create a `.env` file in the project root (you can copy `.env.example`).
    - Add your key to the `.env` file:
      ```
      OPENROUTER_API_KEY=sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxx
      ```
      _(Replace the placeholder with your actual key.)_

4.  **Build the Server:** Compile the TypeScript code.

    ```bash
    npm run build
    ```

## Running the Server

You can run the server directly using Node:

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

Alternatively, configure your MCP client (like Cursor or the Claude desktop app) to launch the server. The server name is `de-tutor` and the binary name (if needed for client config) is also `de-tutor`.

**Example Client Configuration (e.g., for Claude Desktop):**

```json
{
  "mcpServers": {
    "de-tutor": {
      "command": "node",
      "args": ["/full/path/to/your/project/build/index.js"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

_(Ensure the path in `args` is the correct **absolute path** to the built `index.js` file on your system. You might not need the `env` section here if you are already using the `.env` file, as the server loads it directly via `dotenv`.)_

## Using with Cursor

[Cursor](https://cursor.sh/) is an AI-first code editor that can act as an MCP client. Setting up this server with Cursor requires configuring the server launch and potentially setting up a Project Rule for the guidance prompt, although Cursor might also pick up the server-provided prompt.

1.  **Configure Server in Cursor:**

    - Go to `Cursor Settings` > `MCP` > `Add new global MCP server`.
    - Paste in the same JSON as the example client configuration above, ensuring the path to `build/index.js` is correct for your system.

2.  **(Optional) Create a Cursor Project Rule for the Prompt:** If you prefer explicit rules or find Cursor isn't using the server's prompt automatically, you can provide the guidance using Cursor's [Project Rules](https://docs.cursor.com/context/rules-for-ai) feature.

    - Create the directory `.cursor/rules` in your project root if it doesn't exist.
    - Create a file inside it named `de-tutor.rule` (or any `.rule` filename).
    - Paste the following guidance text into `de-tutor.rule`:

      ```text
      You are a helpful assistant connecting to a Data Engineering knowledge server. Your goal is to provide the user with personalized updates about new Data Engineering concepts, patterns, and technologies they haven't encountered yet.

      Available Tools:
      1.  `de_tutor_get_updates`: Fetches recent general news and articles about Data Engineering. Use this first to see what's new.
      2.  `de_tutor_read_memory`: Checks which Data Engineering concepts the user already knows based on their stored knowledge profile.
      3.  `de_tutor_write_memory`: Updates the user's profile to mark whether they have learned or already know a specific Data Engineering concept mentioned in an update.

      Your Workflow:
      1.  Call `de_tutor_get_updates` to discover recent Data Engineering developments.
      2.  Call `de_tutor_read_memory` to understand the user's current knowledge base.
      3.  Present the new developments to the user, highlighting things they likely don't know.
      4.  If the user confirms they know a concept or have learned it, call `de_tutor_write_memory` to update their profile.

      Be concise and focus on delivering relevant, new information tailored to the user's existing knowledge.
      ```

3.  **Connect and Use:**
    - Ensure the `de-tutor` server is enabled in Cursor's MCP settings.
    - If using a rule file: Start a new chat or code generation request (e.g., Cmd+K) and include `@de-tutor-rule` (or whatever you named your rule file) in your request. This tells Cursor to load the rule's content, providing instructions on how to use the tools.
    - If relying on the server prompt: Simply start interacting with Cursor; it should have access to the tools and the guidance prompt provided by the server.

## Features & Usage

This server provides the following capabilities:

- **Resource (`data_engineering_knowledge_memory`):** Stores a simple JSON object in `data/data-engineering-knowledge.json` mapping known concepts (strings) to boolean flags (`true`).
- **Tools:**
  - `de_tutor_read_memory`: Reads the current known concepts from the JSON file.
  - `de_tutor_write_memory`: Updates the JSON file to mark a concept as known (`true`) or unknown (`false`). Takes `concept` (string) and `known` (boolean) as input.
  - `de_tutor_get_updates`: Uses your OpenRouter API key to query Perplexity (`perplexity/sonar-small-online`) for recent Data Engineering news, patterns, and technologies.
- **Prompt (`data-engineering-tutor-guidance`):** Provides instructions to the connected AI client on how to use the tools in a workflow:
  1. Get latest updates.
  2. Read known concepts from memory.
  3. Present new information to the user.
  4. Update memory based on user feedback.

## Development & Debugging

- **Build:** `npm run build` compiles TypeScript to JavaScript in the `build/` directory.
- **Code Structure:** See `src/` for implementation details:
  - `src/index.ts`: Server entry point. Imports `McpServer` and `StdioServerTransport` from specific SDK paths. Instantiates `McpServer`. Imports and calls registration functions (`registerPrompts`, `registerResources`, `registerTools`) from other modules, passing the server instance. Sets up and connects the server using `StdioServerTransport`.
  - `src/prompts/index.ts`: Defines the guidance prompt text. Exports `registerPrompts`, which takes the `McpServer` instance and uses `server.prompt()` to register the static guidance prompt with its callback.
  - `src/resources/index.ts`: Exports `KnowledgeMemory` type and helper functions (`readMemoryFile`, `writeMemoryFile`) for file I/O on `data/data-engineering-knowledge.json`. Exports `registerResources`, which takes the `McpServer` instance and uses `server.resource()` to register the `data_engineering_knowledge_memory` resource with a specific URI and a `ReadResourceCallback`.
  - `src/tools/index.ts`: Exports `registerTools`, which takes the `McpServer` instance and uses `server.tool()` to register each tool (`de_tutor_read_memory`, `de_tutor_write_memory`, `de_tutor_get_updates`). Defines input schemas using Zod where necessary (for `write_memory`). Tool functions use helpers from `resources/index.ts` or `fetch` to perform actions and return results in the expected format.
- **MCP Inspector:** Use `@modelcontextprotocol/inspector` to see raw message flow:
  ```bash
  npx @modelcontextprotocol/inspector node ./build/index.js
  ```
  _(Ensure `OPENROUTER_API_KEY` is set in your environment if running this way and not relying solely on the `.env` file loaded by the server itself.)_

## Notes

- This server uses a simple file (`data/data-engineering-knowledge.json`) for storing user knowledge. For more robust applications, consider a proper database.
- Error handling is basic; production servers would need more comprehensive error management.

## Wrapping up

This demo demonstrates the core steps involved in creating a functional MCP server using the TypeScript SDK and the `McpServer` class. We defined a resource to manage state, tools to perform actions (including interacting with an external API), and a prompt to guide the AI client.

This provides a foundation for building more complex and useful agentic capabilities with MCP.

(Also, if you run into any 🐛bugs, feel free to open up an issue.)