Quick Start

This guide will walk you through setting up and running the server project and understanding its basic workflow.

Prerequisites

• Node.js >= 18
• pnpm (recommended)
• A valid OpenAI API Key

---

Step 1: Install Dependencies

First, clone the entire monorepo (if you haven't already), then navigate into the server directory and install its dependencies.

# Assuming you are in the monorepo's root directory
cd server
pnpm install

Step 2: Configure Environment Variables

The server project needs to connect to the OpenAI service. You'll need to create a .env file and add your API key.

1. In the server directory, create a new file named .env.

2. Add the following content to the .env file:

   OPENAI_API_KEY="sk-..."

   Replace sk-... with your own OpenAI API key.

Step 3: Understand the Tool Schema

The server needs to know what components (tools) are available on the client. This is achieved through a file like mcp-comp-schema.json.

In our example setup, the express service attempts to load this schema from a predefined path or an environment variable. To get started quickly, you can copy the mcp-comp-schema.json file generated by the client project into the server/servers/express/src/config directory, or configure the corresponding environment variable to point to the file.

In a typical development workflow, the Vite plugin on the client side would automatically push this schema to an endpoint on the server.

Step 4: Start the Development Server

Now you can start the express development server.

pnpm dev:express

This command will:

1. First, build the mcpServers package.
2. Then, start the express server in hot-reload mode.

By default, the server will run at http://localhost:3000.

Step 5: Test the API

You can use curl or any API testing tool to send a request to the server to simulate a chat interaction.

curl -X POST http://localhost:3000/api/message \
-H "Content-Type: application/json" \
-d '{
  "messages": [
    {
      "role": "user",
      "content": "Recommend a few books to me"
    }
  ]
}'

Observe the server's console output and the returned JSON data. If your query triggers a tool (like RecommendBook), you will see the toolName and componentProps fields in the returned meta object.

If the returned data has a toolName other than null, congratulations! The server has successfully converted your natural language request into a UI component rendering command.