Building a CSS Tutor MCP Server

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

This server demonstrates key MCP concepts: defining Resources, Tools, and Prompts. The goal of this demonstration is to help you move on from here and build much larger and more interesting agentic capabilities.

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., the Claude desktop app)
• An OpenRouter API Key (for fetching live CSS updates via Perplexity)

Quick Start

Follow these steps to get the server running quickly:

1. Clone the Repository:

git clone https://github.com/3mdistal/css-mcp-server.git
    cd css-mcp-server

2. Install Dependencies:

npm install # Or: yarn install / pnpm install

3. Prepare API Key: The `get_latest_updates` tool requires an OpenRouter API key. Obtain your key from OpenRouter. You will provide this key to your MCP client in Step 5.

4. Build the Server: Compile the TypeScript code.

npm run build # Or: yarn build / pnpm run build

5. Configure Your MCP Client: Tell your client how to launch the server *and* provide the API key as an environment variable. Here's an example for the Claude desktop app's `claude_desktop_config.json`:

{
      "mcpServers": {
        "css-tutor": {
          "command": "node",
          "args": [
            "/full/path/to/your/css-mcp-server/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. Replace the placeholder API key.)*

6. Connect: Start the connection from your MCP client. The client will launch the server process (with the API key in its environment), and you can start interacting!

Using with Cursor

Cursor is an AI-first code editor that can act as an MCP client. Setting up this server with Cursor is straightforward, but requires an extra step for the guidance prompt.

1. Configure Server in Cursor:

2. Create a Cursor Project Rule for the Prompt: Cursor currently does not automatically use MCP prompts provided by servers. Instead, you need to provide the guidance using Cursor's Project Rules feature.

You are a helpful assistant connecting to a CSS knowledge server. Your goal is to provide the user with personalized updates about new CSS features they haven't learned yet.

        Available Tools:
        1.  `get_latest_updates`: Fetches recent general news and articles about CSS. Use this first to see what's new.
        2.  `read_from_memory`: Checks which CSS concepts the user already knows based on their stored knowledge profile.
        3.  `write_to_memory`: Updates the user's knowledge profile. Use this when the user confirms they have learned or already know a specific CSS concept mentioned in an update.

        Workflow:
        1.  Call `get_latest_updates` to discover recent CSS developments.
        2.  Call `read_from_memory` to get the user's current known concepts (if any).
        3.  Compare the updates with the known concepts (if any). Identify 1-2 *new* concepts relevant to the user. **Important: They _must_ be from the response returned by `get_latest_updates` tool.**
        4.  Present these new concepts to the user, adding any context as needed, in addition to the information returned by the `get_latest_updates`.
        5.  Ask the user if they are familiar with these concepts or if they've learned them now.
        6.  If the user confirms knowledge of a concept, call `write_to_memory` to update their profile for that specific concept.
        7.  Focus on providing actionable, personalized learning updates.

3. Connect and Use:

Note that _without_ the prompt/rule, Cursor will still be able to use individual tools if you ask it to. The prompt provides a workflow and order in which to call the tools and read/write from memory.

Understanding the Code

This section provides a higher-level overview of how the server is implemented.

MCP Concepts Used

• Resource (`css_knowledge_memory`): Represents the user's known CSS concepts, stored persistently in `data/memory.json`.
• Tools: Actions the server can perform:
• Prompt (`css-tutor-guidance`): Static instructions guiding the AI client on how to interact with the tools and resource effectively.

Code Structure

The code is organized as follows:

• `data/memory.json`: A simple JSON file acting as the database for known CSS concepts. A default version is included in the repo.
• `src/resources/index.ts`: Defines the `css_knowledge_memory` resource. It includes:
• `src/tools/index.ts`: Defines the three tools using `server.tool`:
• `src/prompts/index.ts`: Defines the static `css-tutor-guidance` prompt using `server.prompt`. The prompt text is embedded directly in the code.
• `src/index.ts`: The main server entry point.
• `package.json`: Defines dependencies (`@modelcontextprotocol/sdk`, `dotenv`, `node-fetch`, `zod`) and the `build` script (`tsc`).
• `.env.example` / `.env`: Used for storing the `OPENROUTER_API_KEY` (if using Option A for configuration).
• `.gitignore`: Configured to ignore `node_modules`, `build`, `.env`, and the contents of `data/` except for the default `data/memory.json`.
• `tsconfig.json`: Standard TypeScript configuration.

Debugging with MCP Inspector

If you need to debug the server or inspect the raw JSON-RPC messages being exchanged, you can use the `@modelcontextprotocol/inspector` tool. This tool acts as a basic MCP client and launches your server, showing you the communication flow.

Run the inspector from your terminal in the project root:

npx @modelcontextprotocol/inspector node ./build/index.js

Explanation:

• `npx @modelcontextprotocol/inspector`: Downloads (if needed) and runs the inspector package.
• `node`: The command used to execute your server.
• `./build/index.js`: The path (relative to your project root) to your compiled server entry point.

Environment Variables for Inspector:

Note that the inspector launches your server as a child process. If your server relies on environment variables (like `OPENROUTER_API_KEY` for the `get_latest_updates` tool), you need to ensure they are available in the environment where you run the `npx` command. The `.env` file might not be automatically loaded in this context. You can typically prefix the command:

# Example on Linux/macOS
OPENROUTER_API_KEY="sk-or-xxxxxxxxxx" npx @modelcontextprotocol/inspector node ./build/index.js

# Example on Windows (Command Prompt)
set OPENROUTER_API_KEY=sk-or-xxxxxxxxxx && npx @modelcontextprotocol/inspector node ./build/index.js

# Example on Windows (PowerShell)
$env:OPENROUTER_API_KEY="sk-or-xxxxxxxxxx"; npx @modelcontextprotocol/inspector node ./build/index.js

Replace `sk-or-xxxxxxxxxx` with your actual key.

Wrapping up

This demo demonstrates the core steps involved in creating a functional MCP server using the TypeScript SDK. 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.

Hope this demo can help you understand how to build servers that are much more complex (and useful) than this one!

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