CSS Tutor

Fornece atualizações personalizadas e tutoriais sobre recursos de CSS usando a API OpenRouter.

GitHubExperimente este MCPPatrocinado

Documentação

Construindo um Servidor MCP CSS Tutor

Este repositório contém um servidor simples de Protocolo de Contexto de Modelo (MCP) construído com Node.js e TypeScript. Ele atua como um "CSS Tutor", fornecendo atualizações personalizadas sobre recursos de CSS para um cliente de IA conectado.

Este servidor demonstra conceitos-chave do MCP: definição de Recursos, Ferramentas e Prompts. O objetivo desta demonstração é ajudar você a avançar a partir daqui e construir capacidades agênticas muito maiores e mais interessantes.

Pré-requisitos

  • Node.js (v18 ou posterior recomendado)
  • npm (ou seu gerenciador de pacotes Node.js preferido, como yarn ou pnpm)
  • Um cliente de IA capaz de se conectar a um servidor MCP (por exemplo, o aplicativo de desktop Claude)
  • Uma Chave de API OpenRouter (para buscar atualizações de CSS ao vivo via Perplexity)

Início Rápido

Siga estes passos para colocar o servidor em funcionamento rapidamente:

  1. Clone o Repositório:

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

  2. Instale as Dependências:

    npm install # Or: yarn install / pnpm install

  3. Prepare a Chave de API: A ferramenta get_latest_updates requer uma chave de API OpenRouter. Obtenha sua chave em OpenRouter. Você fornecerá esta chave ao seu cliente MCP no Passo 5.

  4. Compile o Servidor: Compile o código TypeScript.

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

  5. Configure Seu Cliente MCP: Informe ao seu cliente como iniciar o servidor e forneça a chave de API como uma variável de ambiente. Aqui está um exemplo para o claude_desktop_config.json do aplicativo de desktop Claude:

    {
  "mcpServers": {
    "css-tutor": {
      "command": "node",
      "args": [
        "/full/path/to/your/css-mcp-server/build/index.js"
      ],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

    (Certifique-se de que o caminho em args seja o caminho absoluto correto para o arquivo index.js compilado no seu sistema. Substitua a chave de API de exemplo.)

  6. Conecte: Inicie a conexão a partir do seu cliente MCP. O cliente iniciará o processo do servidor (com a chave de API em seu ambiente), e você poderá começar a interagir!

Usando com Cursor

Cursor é um editor de código com foco em IA que pode atuar como cliente MCP. Configurar este servidor com Cursor é simples, mas requer um passo extra para o prompt de orientação.

  1. Configure o Servidor no Cursor:

    • Vá para Cursor Settings > MCP > Add new global MCP server.
    • Cole o mesmo JSON do passo do Claude Desktop, com todas as mesmas ressalvas.

  2. Crie uma Regra de Projeto no Cursor para o Prompt: O Cursor atualmente não usa automaticamente prompts MCP fornecidos pelos servidores. Em vez disso, você precisa fornecer a orientação usando o recurso de Regras de Projeto do Cursor.

    • Crie o diretório .cursor/rules na raiz do seu projeto, se ele não existir.

    • Crie um arquivo dentro dele chamado css-tutor.rule (ou qualquer nome de arquivo .rule).

    • Cole o seguinte texto de orientação em css-tutor.rule:

      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. Conecte e Use:

    • Certifique-se de que o servidor css-tutor esteja habilitado nas configurações MCP do Cursor.
    • Inicie uma nova solicitação de chat ou geração de código (por exemplo, Cmd+K) e inclua @css-tutor-rule (ou como você nomeou seu arquivo de regra) na sua solicitação. Isso informa ao Cursor para carregar o conteúdo da regra, que inclui as instruções sobre como usar as ferramentas read_from_memory, write_to_memory e get_latest_updates fornecidas pelo servidor MCP conectado.

Observe que sem o prompt/regra, o Cursor ainda poderá usar ferramentas individuais se você pedir. O prompt fornece um fluxo de trabalho e uma ordem para chamar as ferramentas e ler/gravar na memória.

Entendendo o Código

Esta seção fornece uma visão geral de alto nível de como o servidor é implementado.

Conceitos MCP Utilizados

  • Recurso (css_knowledge_memory): Representa os conceitos de CSS conhecidos do usuário, armazenados persistentemente em data/memory.json.
  • Ferramentas: Ações que o servidor pode executar:
    • get_latest_updates: Busca notícias de CSS do OpenRouter/Perplexity.
    • read_from_memory: Lê o conteúdo do recurso css_knowledge_memory.
    • write_to_memory: Modifica o recurso css_knowledge_memory.
  • Prompt (css-tutor-guidance): Instruções estáticas que orientam o cliente de IA sobre como interagir efetivamente com as ferramentas e o recurso.

Estrutura do Código

O código está organizado da seguinte forma:

  • data/memory.json: Um arquivo JSON simples que atua como banco de dados para conceitos de CSS conhecidos. Uma versão padrão está incluída no repositório.
  • src/resources/index.ts: Define o recurso css_knowledge_memory. Inclui:
    • Um esquema Zod para validar os dados.
    • Funções readMemory e writeMemory para E/S de arquivos.
    • Registro usando server.resource, especificando o esquema de URI memory:// e permissões de leitura/gravação. O manipulador de leitura retorna o conteúdo de data/memory.json.
  • src/tools/index.ts: Define as três ferramentas usando server.tool:
    • read_from_memory: Chama readMemory.
    • write_to_memory: Recebe concept e known como entrada (esquema definido com Zod), usa readMemory e writeMemory para atualizar o arquivo JSON.
    • get_latest_updates: Requer OPENROUTER_API_KEY, chama a API OpenRouter usando node-fetch e o modelo perplexity/sonar-pro, retorna o resumo gerado por IA.
  • src/prompts/index.ts: Define o prompt estático css-tutor-guidance usando server.prompt. O texto do prompt está embutido diretamente no código.
  • src/index.ts: O ponto de entrada principal do servidor.
    • Inicializa a instância McpServer de @modelcontextprotocol/sdk.
    • Importa e chama as funções registerPrompts, registerResources e registerTools dos outros módulos.
    • Usa StdioServerTransport para lidar com a comunicação via entrada/saída padrão.
    • Conecta o servidor ao transporte e inclui tratamento básico de erros.
  • package.json: Define dependências (@modelcontextprotocol/sdk, dotenv, node-fetch, zod) e o script build (tsc).
  • .env.example / .env: Usados para armazenar o OPENROUTER_API_KEY (se usar a Opção A para configuração).
  • .gitignore: Configurado para ignorar node_modules, build, .env e o conteúdo de data/, exceto o data/memory.json padrão.
  • tsconfig.json: Configuração padrão do TypeScript.

Depuração com o MCP Inspector

Se você precisar depurar o servidor ou inspecionar as mensagens JSON-RPC brutas sendo trocadas, você pode usar a ferramenta @modelcontextprotocol/inspector. Esta ferramenta atua como um cliente MCP básico e inicia seu servidor, mostrando o fluxo de comunicação.

Execute o inspector a partir do seu terminal na raiz do projeto:

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

Explicação:

  • npx @modelcontextprotocol/inspector: Baixa (se necessário) e executa o pacote do inspector.
  • node: O comando usado para executar seu servidor.
  • ./build/index.js: O caminho (relativo à raiz do seu projeto) para o ponto de entrada do servidor compilado.

Variáveis de Ambiente para o Inspector:

Observe que o inspector inicia seu servidor como um processo filho. Se o seu servidor depende de variáveis de ambiente (como OPENROUTER_API_KEY para a ferramenta get_latest_updates), você precisa garantir que elas estejam disponíveis no ambiente onde você executa o comando npx. O arquivo .env pode não ser carregado automaticamente neste contexto. Você pode normalmente prefixar o comando:

# 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

Substitua sk-or-xxxxxxxxxx pela sua chave real.

Concluindo

Esta demonstração mostra os passos principais envolvidos na criação de um servidor MCP funcional usando o SDK TypeScript. Definimos um recurso para gerenciar estado, ferramentas para executar ações (incluindo interação com uma API externa) e um prompt para orientar o cliente de IA.

Esperamos que esta demonstração ajude você a entender como construir servidores muito mais complexos (e úteis) do que este!

(Além disso, se você encontrar algum 🐛bug, sinta-se à vontade para abrir uma issue.)