Forem: Yevheni Kshevitskyi

Storyblok MCP Client

Yevheni Kshevitskyi — Tue, 25 Mar 2025 13:29:00 +0000

Faster CMS Integration

Storyblok MCP Client is a tool that connects @storyblokcom, a headless CMS, with an AI agent through Model Context Protocol (MCP), enabling AI agents to interact with the CMS using human language 🙊

This makes it super easy to pull Storyblok content straight into the client app (eg. Cursor IDE) without manual API calls or extra setup.

📢 In this article: I’ll walk you through setting up the Storyblok MCP Client in the Cursor IDE, including:

Creating a Storyblok Personal Access Token
Configuring Cursor IDE’s MCP Server
Create new Storyblok space from Cursor IDE chat prompt and fetching component type definitions.

⚡ TL;DR

📦 NPM Package: @slvrio/storyblok-mcp-client
🔗 GitHub Repo: Storyblok MCP Client

So, Storyblok MCP ... wtf? 🤨

Working with a headless CMS usually means managing API calls and dealing with custom integrations. Storyblok MCP Client (server) flips all that on its head, letting AI agents access Storyblok content directly and interact with it using human language in chat prompts. 🙌

How It Works

Storyblok MCP Client (server) acts as a bridge between Storyblok’s API and AI agents, providing additional context to the AI agents through MCP tools. ⚡

✨ Available Tools (as of `v.0.0.1`)

spaces_create — Create a new Storyblok space.
spaces_get — Retrieve a list of Storyblok spaces.
components_get — Fetch all components within a space.
component_get — Retrieve a specific component by ID.
typedefs_get — Generate TypeScript type definitions for components.

Setup

Let's get started with setting up everything we need for the Storyblok MCP Client!

Create a Storyblok Personal Access Token (PAT)
Configure Cursor IDE’s MCP Server
Create a new space directly from Cursor IDE’s chat prompt and fetch Storyblok component type definitions

Let’s walk through each step to get everything up and running smoothly! 😎

1. 🔑 Create a Storyblok Personal Access Token (PAT)

First of all make sure to create an account at Storyblok.com, if you dont have one.

Navigate to: My Account 👉 Account Settings 👉 Personal access token
Click on Generate new token, fill in the fields:
- Name: Any name
- Expiration: Select token expiration date (default 30days)
Click Generate & Copy token

Note. Please copy this personal access token now. It will be visible only once

View high resolution screenshot here

2. ⚙️ Configure Cursor IDE’s MCP Server

Open Cursor IDE settings
Navigate to the MCP tab
Click on Add new MCP server
Fill in the fields:
- Name: Any name
- Type: command
- Command: npx -y @slvrio/storyblok-mcp-client --token=<YOUR_STORYBLOK_PAT_FROM_STEP_1>
Click Save

View high resolution screenshot here

⚠️ Cursor v0.47.8

In Cursor v0.47.8, MCP server configurations are managed in mcp.json.

To setup Storyblok MCP Client, simply add the following config under the mcpServers object:

"Storyblok": {
  "command": "npx",
  "args": [
    "-y",
    "@slvrio/storyblok-mcp-client",
    "--token=<YOUR_STORYBLOK_PAT_FROM_STEP_1>"
  ]
}

Note. You can also define the STORYBLOK_PERSONAL_API_TOKEN as environment variable, if set you can omit --token argument in the command.

View high resolution screenshot here

3. 🤖 Let's Chat

3.1 Create new Storyblok space

To create a new space, go to the chat (cmd+i), type the following prompt, and press Enter:

Create new storyblok space with name "Hello, world!"

Tool spaces_create

View high resolution screenshot here

Once the space is created, you'll see the metadata, including the Space ID

To view and list all your Storyblok spaces, type:

List my storyblok spaces

Tool spaces_get

3.2 View available Storyblok components

To view the components for your Storyblok space, type the following prompt and press Enter:

List all components for space #<SPACE_ID>

Tool components_get
Note: The SPACE_ID is conditionally required. You can either:

Use the Space ID from Step 1 and pass it with prompt text,

Set the STORYBLOK_SPACE_ID environment variable,

Or pass the --space_id argument directly in the command.

View high resolution screenshot here

3.3 Typescript. Fetch Storyblok component type definitions

To generate TypeScript type definitions for your Storyblok components, type the following prompt and press Enter:

Fetch ts types for components in storyblok space #<SPACE_ID>

Tool typedefs_get

This will fetch the type definitions, making it easier to integrate Storyblok components into your TypeScript-based project. 📦

Uff, that's it! With Storyblok MCP Client, we’ve enabled natural language interactions with the Storyblok API directly in the Cursor IDE chat. We’ve explored how to set up the MCP server, manage Storyblok spaces, and fetch component types.

Thanks for reading! 🙌

Using MCP in Cursor IDE: A Simple Tool for CrossFit WOD

Yevheni Kshevitskyi — Mon, 24 Mar 2025 14:58:32 +0000

I've been exploring Model Context Protocol (MCP), an innovative standard that enables AI agents to interact with external tools and data sources. MCP is particularly valuable in environments like Cursor IDE, where AI-driven automation can simplify routine tasks and improve developer efficiency.

To explore this, I built @slvrio/wod, a simple MCP tool that fetches the Workout of the Day (WOD) from the CrossFit API. It's an example of how MCP can help bring external data into your workflow, specifically for AI agents.

For more detailed information about Model Context Protocol (MCP), refer to the Get started with the Model Context Protocol (MCP).

⚡ TL;DR

Built an MCP tool to fetch the CrossFit Workout of the Day (WOD)
Published on npm: @slvrio/wod
Code on GitHub: mcp-tool/wod

Setup MCP Server in Cursor IDE

You can integrate @slvrio/wod into Cursor IDE by setting up an MCP server, enabling retrieval of CrossFit's WOD directly within the IDE 🙈

1. Add a new MCP Server in Cursor IDE

Open Cursor IDE.
Navigate to Settings ➡️ Features ➡️ MCP.
Click on "+ Add New MCP Server".
In the configuration dialog:
- Name: Enter a descriptive name, e.g., "CF WOD".
- Type: Select "command".
- Command: Enter the command to run the WOD tool:
```
npx -y @slvrio/wod
```
Click "Save" to add the MCP server.

2. Use the WOD Tool in Cursor IDE

With the MCP server configured:

Open the Chat (cmd+i) in Cursor IDE.
In the chat interface, type wod and execute the command.
The tool will fetch and display the latest CrossFit WOD directly within the chat.

This is just a small step in experimenting with MCP-powered AI tooling. If you’re exploring AI agents, MCP, or automation, I’d love to hear your thoughts!

Breaking Monoliths: Transforming Legacy Codebase with NX Monorepo

Yevheni Kshevitskyi — Mon, 10 Mar 2025 11:37:50 +0000

In any long-running software project, architecture is key to scalability, maintainability, and a smooth developer experience. This article dives into the story of a bold architectural shift that transformed a legacy monolith into a sleek, modular system—boosting flexibility, future-proofing the codebase, and making development a whole lot more enjoyable 🚀.

The Challenge: A Legacy Codebase Under Pressure

The legacy project in question had been in operation for approximately four years. Over time, it evolved into a multi-app frontend ecosystem built atop a modern stack—primarily Vue—integrated with REST APIs. While the setup allowed for rapid prototyping and delivery, it also became a bottleneck as the project scaled. The following issues surfaced:

Performance Decline: Adding new apps slowed builds and affected performance.
Development Experience (DX): With multiple developers working on the same codebase, merge conflicts became a regular occurrence.
Bugs: Unexpected bugs surfaced due to intertwined dependencies and a lack of clear boundaries.
Scalability: A monolithic structure hindered the team's ability to iterate and grow efficiently.

These challenges made it clear that the project's architecture needed a serious rethink.

Researching Solutions: Modularization with NX monorepo

Determined to address these pain points, I began researching ways to modularize the codebase while adhering to domain-driven design (DDD) principles. The goal was to split the monolithic codebase into self-contained, maintainable modules without sacrificing the integrity of the system.

My research led me to NX, a powerful monorepo tool designed for scalable application development. NX offered:

Modularization: Clear separation of apps and libraries into distinct domains.
Improved Performance: Incremental builds and caching reduced build times.
Enhanced Collaboration: Logical module boundaries reduced merge conflicts and allowed teams to work independently.
Modern Tooling: Built-in support for advanced frontend frameworks like Vue and Svelte, combined with testing and linting capabilities.

The Proof of Concept: Bringing the Team on Board

To validate the potential benefits of NX, I created a proof-of-concept (PoC) demonstrating how the legacy codebase could be restructured. The PoC showcased:

Clear separation of features into libraries aligned with DDD principles.
Incremental builds, which significantly reduced build times.
Simplified collaboration, as each team could now focus on their module without affecting others.

Presenting the PoC to the team was a turning point—it got everyone aligned on the vision for a more modular, scalable future.

Making It Happen: The Migration 🚀

Following the approval of the PoC, the team embarked on implementing the NX monorepo structure. The transformation involved:

Migration: Gradually moving apps and shared functionality into NX libraries.
Refactoring: Aligning components and services with DDD principles.
Optimization: Leveraging NX's caching and dependency graph to improve build and test processes.

This change had a huge impact:

Improved DX: Developers reported fewer merge conflicts and an overall smoother workflow.
Faster Builds: Incremental builds slashed build times significantly ⚡.
Scalability: The modular architecture made it easier to onboard new apps and developers.

Key Takeaways

This journey underscores the importance of re-evaluating architectural decisions as projects evolve. By introducing NX into the legacy project, we:

Shifted from a monolithic, hard-to-scale structure to a modular, domain-driven architecture.
Future-proofed our frontend, making it more maintainable and adaptable.
Boosted developer productivity and collaboration in ways that were immediately felt.

For teams struggling with monolithic setups, embracing a monorepo strategy like NX can be a total game-changer. The migration might take effort, but the long-term benefits—for both the codebase and the people working on it—are 100% worth it 💡

Automatically Generating TypeScript Types from Storyblok Components

Yevheni Kshevitskyi — Mon, 10 Mar 2025 10:08:36 +0000

⚡ TL;DR

Use Storyblok CLI and emeraldwalk.runonsave to automate TypeScript type generation for Storyblok components.

Find the full source code here: Storyblok TypeScript Types Generator

If you're using Storyblok with TypeScript, ensuring type safety can significantly enhance your development experience. Instead of manually defining types, you can automatically generate TypeScript types from your Storyblok component schema. This tutorial will guide you through setting up a Storyblok TypeScript types generation.

📦 Setting Up the Type Generator

1. Install Dependencies

First, ensure that you have Node.js v20+ installed. Then, install the necessary packages:

npm i -D storyblok

2. Authenticate with Storyblok

You'll need to log in to Storyblok CLI to fetch your component schemas. Run the following command:

npx storyblok login

3. Configure Your Space ID

Create a .env.local file in your project root and add your Storyblok Space ID:

STORYBLOK_SPACE_ID=your_space_id_here

4. Create the Type Generation Script

If you haven't cloned the repository, create a new script file to generate Storyblok types. Inside your project, create a directory called scripts/ and a file named storyblok.sh:

mkdir -p scripts && touch scripts/storyblok.sh

Then, open scripts/storyblok.sh and add the following content:

Let's break down what this script does:

Loads the Storyblok Space ID from .env.local
Pulls component schemas from Storyblok and saves them to __storyblok__/components.schema.json
Runs storyblok generate-typescript-typedefs to generate TypeScript types inside types/storyblok.d.ts

Make sure the script is executable:

chmod +x scripts/storyblok.sh

Then, add a corresponding script in package.json:

{
  "scripts": {
    "storyblok:types": "bash scripts/storyblok.sh"
  }
}

⚡ Generating TypeScript Types

To manually generate TypeScript types, execute:

npm run storyblok:types

This will:

Fetch components from Storyblok
Save them to __storyblok__/components.schema.json
Generate TypeScript types inside types/storyblok.d.ts

🏗 Automating Type Updates with VS Code

You can automate type generation every time you update your Storyblok schema. But there's a catch—it won’t just work out of the box. You’ll need to install the emeraldwalk.runonsave VS Code extension and configure it.

1. Install the Extension

Install emeraldwalk.runonsave from the VS Code marketplace.

2. Configure settings.json

Add the following configuration to your VS Code settings.json file:

{
  "emeraldwalk.runonsave": {
    "shell": "/bin/bash",
    "commands": [
      {
        "match": "__storyblok__/.*\\.json$",
        "cmd": "bash scripts/storyblok.sh"
      }
    ]
  }
}

This setup ensures that whenever a .json file inside __storyblok__/ is saved, the storyblok.sh script runs automatically, keeping your TypeScript definitions up to date.

✅ Conclusion

And that's it! With just a little setup, you now have fully automated TypeScript types for your Storyblok components. No more manual type definitions—just clean, reliable, and always up-to-date types.

List Strava Activities in a Next.js App

Yevheni Kshevitskyi — Sat, 08 Feb 2025 15:25:02 +0000

Prerequisites

A basic understanding of Next.js and TypeScript
An active Strava account
Access to the Strava API (client ID, client secret, and refresh token)
A GitHub repository for your Next.js project

Step 1: Setting Up Strava API Service

To simplify Strava API integration, we'll create a new service:

Step 2: Fetching and Displaying Activities in a Component

To display activities on the frontend, you’ll need to fetch the necessary data and pass it to your React component. In this step, we fetch the data using getStaticProps, which allows the page content and activities to be pre-rendered at build time.

Eg. in pages/index.tsx, the data is fetched by calling fetchExtendedActivities, which retrieves activities data from Strava API. The fetched data is then returned as props, which are passed to the component.

Here’s how you can implement this:

Step 4: Configuring GitHub Cron Job

To automate tasks like data fetching, deployments, or updates on a regular basis, you can use a GitHub cron job by configuring a scheduled workflow. This will allow you to trigger your workflow at specific times, such as once a day, at a specific hour, or on particular days of the week.

# Trigger the workflow once a day (adjust the schedule as needed)
schedule:
  - cron: "0 0 * * *" # run the workflow at midnight UTC every day

After the job runs, you can monitor the results and logs from the Actions tab in your GitHub repository. If the cron job fails or produces unexpected results, the logs will help you troubleshoot and adjust the workflow accordingly.

Adding an API Route (Optional)

Since we're using Next.js with SSG mode to generate distribution artefacts for GitHub Pages, we'll call the fetchExtendedActivities method inside getStaticProps. However, if you want to serve data (activities) from Strava API dynamically to your frontend, consider adding an API route in your Next.js app:

Conclusion

You’ve now set up a Next.js app that pulls in Strava activities, built a backend service, and set up a GitHub cron job to keep things updated regularly. This setup is super flexible, so you can tweak and expand it however you need as your project grows.

Refs.

Image Credits
Photo by Luke Chesser on Unsplash

Forem: Yevheni Kshevitskyi

Storyblok MCP Client

Faster CMS Integration

⚡ TL;DR

So, Storyblok MCP ... wtf? 🤨

How It Works

✨ Available Tools (as of v.0.0.1)

Setup

1. 🔑 Create a Storyblok Personal Access Token (PAT)

2. ⚙️ Configure Cursor IDE’s MCP Server

⚠️ Cursor v0.47.8

3. 🤖 Let's Chat

3.1 Create new Storyblok space

3.2 View available Storyblok components

3.3 Typescript. Fetch Storyblok component type definitions

Using MCP in Cursor IDE: A Simple Tool for CrossFit WOD

⚡ TL;DR

Setup MCP Server in Cursor IDE

1. Add a new MCP Server in Cursor IDE

2. Use the WOD Tool in Cursor IDE

Breaking Monoliths: Transforming Legacy Codebase with NX Monorepo

The Challenge: A Legacy Codebase Under Pressure

Researching Solutions: Modularization with NX monorepo

The Proof of Concept: Bringing the Team on Board

Making It Happen: The Migration 🚀

Key Takeaways

Automatically Generating TypeScript Types from Storyblok Components

⚡ TL;DR

📦 Setting Up the Type Generator

1. Install Dependencies

2. Authenticate with Storyblok

3. Configure Your Space ID

4. Create the Type Generation Script

⚡ Generating TypeScript Types

🏗 Automating Type Updates with VS Code

1. Install the Extension

2. Configure settings.json

✅ Conclusion

List Strava Activities in a Next.js App

Step 1: Setting Up Strava API Service

Step 2: Fetching and Displaying Activities in a Component

Step 4: Configuring GitHub Cron Job

Adding an API Route (Optional)

Conclusion

✨ Available Tools (as of `v.0.0.1`)