Content
# supOS MCP Server
This MCP server is developed based on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) protocol using the `typescript-sdk`, allowing any client that supports the MCP protocol to utilize it.
It provides a series of open APIs for supOS, such as querying the topic tree structure, topic details, and more.
## Supported APIs
### Tools
1. `get-model-topic-tree`
- Query the topic tree structure menu data
- Input:
- `key` (string): Fuzzy search keyword for child nodes
- `showRec` (boolean): Number of records to display
- `type` (string): Search type: 1--Text search, 2--Tag search
- Returns: Topic tree structure menu data
2. `get-model-topic-detail`
- Get details of a specific topic
- Input:
- `topic` (string): The topic path corresponding to the model
- Returns: Details of a specific topic
3. `get-topic-realtime-data`
- Get real-time data for a specific topic
- Input:
- `topic` (string): The topic path corresponding to the model
- Returns: Real-time data for a specific topic
4. `get-all-topic-realtime-data`
- Get and analyze real-time data for all topics
- Returns: Real-time data for all topics
***Now let's use the documentation together***
## Getting Started
### System Requirements
- Node.js
### Installing the Client
Currently, there are many clients that support the MCP protocol, such as the desktop application `Claude for Desktop`, or some plugins for IDEs (like the `Cline` plugin for `VSCode`). To learn about supported clients, you can visit [Model Context Protocol Client](https://modelcontextprotocol.io/clients).
Here, we will take `Claude for Desktop` as an example.
- Download [Claude for Desktop](https://claude.ai/download).
- Configure the required MCP server for `Claude for Desktop`.
- - Open your `Claude for Desktop` configuration in a text editor: `~/Library/Application Support/Claude/claude_desktop_config.json`.
- - You can also find the configuration file location by clicking `File -> Setting -> Developer` and then `Edit Config`:
- - After opening the configuration file, add the following content to `claude_desktop_config.json` and restart the application:
*Note: You need to restart the application every time you modify this configuration file for the changes to take effect.*
```json
{
"mcpServers": {
"supos": {
"command": "npx",
"args": [
"-y",
"mcp-server-supos"
],
"env": {
"SUPOS_API_KEY": "<API_KEY>",
"SUPOS_API_URL": "<API_URL>",
"SUPOS_MQTT_URL": "<MQTT_URL>"
}
}
}
}
```
- - Here, `API_URL` is the accessible [supOS Community Edition](https://supos-demo.supos.app/) address. You can obtain the `API_KEY` by logging into the Community Edition, navigating to `DataModeling -> View details of a specific topic -> Data Operation -> Fetch`, and copying the corresponding ApiKey. The `MQTT_URL` can be found by visiting `UNS -> MqttBroker -> Listeners` to see the subscribable addresses.
**Note: The above configuration for the MCP server uses `npx` to pull the `mcp-server-supos` npm package and run it locally to provide services to the client. However, `npx` may encounter issues reading the `env` configuration on `Windows` systems, so you can use the following method to resolve this:**
### Running the Service Locally
You can choose one of the following two methods:
- Install `mcp-server-supos` locally and run it with Node
1. Install
```bash
npm install mcp-server-supos -g
```
2. Find the installation package path, for example: `"C://Users//<USER_NAME>//AppData//Roaming//npm//node_modules//mcp-server-supos//dist//index.js"`
3. Modify the configuration in `claude_desktop_config.json` and restart the application
```json
{
"mcpServers": {
"supos": {
"command": "node",
"args": [
"C://Users//<USER_NAME>//AppData//Roaming//npm//node_modules//mcp-server-supos//dist//index.js"
],
"env": {
"SUPOS_API_KEY": "<API_KEY>",
"SUPOS_API_URL": "<API_URL>",
"SUPOS_MQTT_URL": "<MQTT_URL>"
}
}
}
}
```
- Download the source code of this repository, compile and execute it locally
1. Clone the repository:
```bash
git clone https://github.com/FREEZONEX/mcp-server-supos.git
```
2. Install dependencies
```bash
npm ci
```
3. Compile
```bash
npm run build
```
4. Modify the configuration in `claude_desktop_config.json` and restart the application
```json
{
"mcpServers": {
"supos": {
"command": "node",
"args": [
"<local project path>//dist//index.js"
],
"env": {
"SUPOS_API_KEY": "<API_KEY>",
"SUPOS_API_URL": "<API_URL>",
"SUPOS_MQTT_URL": "<MQTT_URL>"
}
}
}
}
```
### Conclusion
This concludes the tutorial on using this service. Once configured successfully, you can see the corresponding services and tools in the following panel:
### Finally
The [supOS Community Edition](https://supos-demo.supos.app/) has integrated the open-source [open-mcp-client](https://github.com/CopilotKit/open-mcp-client) by the author of `CopilotKit`, and has built-in support for the `mcp-server-supos` service, as well as support for the TypeScript version of `agent`. The source code can be accessed at [supOS-CE-McpClient](https://github.com/FREEZONEX/supOS-CE-McpClient).
