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 (for fetching live Data Engineering updates via Perplexity)

Setup

Clone the Repository:

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

Install Dependencies:
```
npm install
```
Prepare API Key: The de_tutor_get_updates tool requires an OpenRouter API key.
- Obtain your key from OpenRouter.
- 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.)
Build the Server: Compile the TypeScript code.
```
npm run build
```

Running the Server

You can run the server directly using Node:

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):

{
  "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 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.

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.

(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 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:

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.

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:
```
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.)