Css MCP Server

🚀 Building a Simple Server with Model Context Protocol

This project demonstrates how to create a basic MCP server using the TypeScript SDK. The server implements the following features:

• Resource Management: Defines a simple resource (css_knowledge_memory) to store known CSS concepts.
• Tool Interaction: Implements three tools:
  • read_from_memory: Reads data from memory.
  • write_to_memory: Writes data to memory.
  • get_latest_updates: Calls the OpenRouter API to get the latest updates.
• Prompt Guidance: Defines a static prompt (css-tutor-guidance) to guide AI clients on how to interact effectively with tools and resources.

📁 Project Structure

The project's file structure is as follows:

project-root/
├── data/                   # Data directory containing the memory.json database file
├── src/
│   ├── resources/          # Directory for resource definitions
│   ├── tools/              # Directory for tool definitions
│   ├── prompts/            # Directory for prompt definitions
│   └── index.ts           # Main program entry file
├── package.json           # Project dependencies and script configurations
├── tsconfig.json          # TypeScript compiler configuration
└── .gitignore             # Code repository ignore rules

🌐 Environment Variables

To run the server properly, you need to set the following environment variable:

OPENROUTER_API_KEY=your_api_key_here

You can add this environment variable to the .env file or set it directly in the operating system environment.

💻 Code Implementation

Resource Definition (src/resources/index.ts)

import { readFileSync, writeFileSync } from 'fs';
import { resource, ResourceHandler } from '@modelcontextprotocol/sdk';

const memorySchema = z.object({
  concepts: z.record(z.string()),
});

export async function readMemory(): Promise<unknown> {
  try {
    const data = readFileSync('./data/memory.json', 'utf8');
    return JSON.parse(data);
  } catch (error) {
    console.error('Error reading memory:', error);
    throw error;
  }
}

export async function writeMemory(data: unknown): Promise<void> {
  try {
    const isValid = memorySchema.safeParse(data).success;
    if (!isValid) {
      throw new Error('Invalid data format');
    }
    writeFileSync('./data/memory.json', JSON.stringify(data, null, 2));
  } catch (error) {
    console.error('Error writing memory:', error);
    throw error;
  }
}

resource({
  name: 'css_knowledge_memory',
  uriPrefix: 'memory://',
  readHandler: async () => await readMemory(),
  writePermission: true,
  writeHandler: async (data) => await writeMemory(data),
});

Tool Definition (src/tools/index.ts)

import { resource } from '@modelcontextprotocol/sdk';
import { readMemory, writeMemory } from './resources';
import { z } from 'zod';

export const read_from_memory = tool({
  name: 'read_from_memory',
  description: 'Read knowledge base data from memory',
  handler: async () => await readMemory(),
});

export const write_to_memory = tool({
  name: 'write_to_memory',
  description: 'Write new knowledge to memory',
  parameters: {
    concept: z.string().describe('CSS concept to be marked as known'),
    known: z.boolean().describe('Indicates whether the concept is known')
  },
  handler: async ({ concept, known }) => {
    const currentData = await readMemory();
    if (known) {
      // Add to the list of known concepts
      currentData.concepts[concept] = true;
    } else {
      // Remove or mark as unknown
      delete currentData.concepts[concept];
    }
    return await writeMemory(currentData);
  },
});

export const get_latest_updates = tool({
  name: 'get_latest_updates',
  description: 'Get the latest CSS update information',
  handler: async () => {
    try {
      // This should call the actual API to get the latest updates
      // In the example, only static data is returned
      return {
        updates: ['New layout mode for CSS Grid added', 'A known issue in Flexbox fixed']
      };
    } catch (error) {
      console.error('Failed to get updates:', error);
      throw error;
    }
  },
});

Prompt Definition (src/prompts/index.ts)

import { prompt } from '@modelcontextprotocol/sdk';

export const css_tutor_guidance = prompt({
  name: 'css_tutor_guidance',
  description: 'Guide learners on how to master core CSS concepts',
  content: `As an experienced CSS developer, help learners understand and master key CSS concepts. Teach in a clear and organized manner.`
});

Main Program (src/index.ts)

import { createServer } from '@modelcontextprotocol/sdk';
import { css_tutor_guidance } from './prompts';
import { read_from_memory, write_to_memory, get_latest_updates } from './tools';

async function main() {
  try {
    const server = await createServer({
      prompts: [css_tutor_guidance],
      tools: [
        read_from_memory,
        write_to_memory,
        get_latest_updates
      ],
    });

    console.log('Server started, listening at:', server.url);
    await server.start();
  } catch (error) {
    console.error('Failed to start the server:', error);
  }
}

main().catch(console.error);

⚙️ Project Configuration

package.json Configuration

{
  "name": "css_tutor_server",
  "version": "1.0.0",
  "description": "CSS teaching assistant server built on Model Context Protocol.",
  "scripts": {
    "start": "ts-node src/index.ts"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^0.5.0",
    "ts-node": "^10.9.2",
    "typescript": "^5.3.3",
    "zod": "^1.24.0"
  }
}

tsconfig.json Configuration

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["**/*.ts"],
  "exclude": ["node_modules"]
}

🚀 Running the Server

1. Clone the project repository to your local machine:

   git clone https://github.com/yourusername/css-tutor-server.git
   cd css-tutor-server
   

2. Install the dependencies:

   npm install
   

3. Start the server:

   npm start
   

🛠️ Debugging Tools

To assist developers with debugging, the project provides the following debugging tool:

npx @modelcontextprotocol/inspector

After running the above command, an interface will open in your browser, allowing you to view and test the server's status, resources, tools, and prompts.

📄 Project File Structure Explanation

• data/memory.json: Stores known CSS concepts.
• src/resources/: Contains the read and write logic for memory resources.
• src/tools/: Contains specific functional tools that can be executed.
• src/prompts/: Defines teaching prompt content.
• src/index.ts: The server entry file, responsible for initializing and starting the service.

💻 Usage Examples

const server = await createServer({
  prompts: [css_tutor_guidance],
  tools: [
    read_from_memory,
    write_to_memory,
    get_latest_updates
  ],
});

// Start the server
await server.start();

🚨 Error Handling

In src/tools/index.ts, we have added error capture and handling mechanisms for each tool. In a production environment, it is recommended to add additional error monitoring and reporting features.

🚀 Future Extensions

The following extensions can be considered in the future:

1. Data Persistence: Use a database instead of local file storage.
2. Logging System: Integrate a professional log management tool.
3. Authentication and Authorization: Assign permissions to different user roles.
4. Internationalization Support: Support multi-language teaching content.
5. Progress Tracking: Record learners' learning progress and achievements.

📚 References

• Model Context Protocol Official Documentation
• Zod Official Documentation
• TypeScript Official Documentation