English | 中文

supOS MCP Endpoint Server

This service implements the Model Context Protocol (MCP) specification, leveraging the provided typescript-sdk, thus ensuring compatibility with any consumer adhering to the MCP framework.

It exposes a set of supOS external interfaces, specifically for functions like retrieving the hierarchical arrangement of topics and fetching granular topic definitions.

Supported Functionalities (Tools)

Interface Methods

1. retrieve-topic-hierarchy

2. Fetches the structural blueprint or menu representation of topics.

3. Parameters:
   • search_term (string): Keyword for substring matching within descendant nodes.
   • result_limit (integer): The maximum count of entities to include in the returned set.
   • filter_modality (string): Specifies the search vector: '1' for textual content matching, '2' for metadata tag filtering.

4. Output: The resultant topic structural dataset.

5. fetch-topic-metadata

6. Retrieves comprehensive details pertaining to an identified topic entity.

7. Parameters:
   • topic_identifier (string): The unique, fully qualified path referencing the desired model context.

8. Output: Detailed metadata package for the specified topic.

9. stream-topic-live-data

10. Accesses instantaneously updated data streams associated with a designated topic.

11. Parameters:
    • topic_path (string): The canonical identifier path for the relevant model.

12. Output: Current, real-time telemetry or data feed for that topic.

13. aggregate-all-topic-telemetry

14. Gathers and processes the live data feeds from every registered topic.

15. Output: A consolidated report of all active topic data streams.

16. execute-postgres-query

17. Allows direct execution of Structured Query Language (SQL) commands against the underlying PostgreSQL data store.

18. Parameters:
    • sql_command (string): The raw SQL instruction to be processed.
    • query_bindings (list): Optional array containing parameters to safely substitute into the SQL statement.

19. Output: The result set generated by the SQL execution.

20. derive-historical-data-via-pg

21. Facilitates retrieval of archival data for a specified subject.

22. Parameters:
    • user_query_intent (string): Natural language input describing the historical data requested by the user.

23. Output: A sequence of chained prompts designed to guide iterative tool invocation for assembling the complete historical data record.

24. generate-topic-retrieval-sql

25. Constructs the appropriate SQL query required to access specific topic data based on a user's intent.

26. Parameters:
    • user_data_request (string): The user's articulated requirement for which data needs querying.
27. Output: A multi-stage instruction set suitable for step-by-step execution to formulate and run the necessary SQL query.

Consult the provided documentation to commence utilization

Initial Setup Procedures

Prerequisites

• Node.js runtime environment

Client Integration

Numerous client applications support the MCP standard, including desktop environments like Claude for Desktop and IDE extensions such as the Cline plugin for VSCode. Refer to the Model Context Protocol Client directory for a comprehensive list. We will use Claude for Desktop as the primary demonstration case.

• Obtain Claude for Desktop.

• Configure the necessary MCP gateway settings within the client application.

• • Access the configuration file via a text editor: ~/Library/Application Support/Claude/claude_desktop_config.json.
• • Alternatively, locate this file via the application interface by navigating to File -> Setting -> Developer and selecting Edit Config:

• • Append the subsequent JSON block to your claude_desktop_config.json file and reload the application. (A restart is mandatory for configuration changes to take effect.)

    { "mcpServers": { "supos": { "command": "npx", "args": [ "-y", "mcp-server-supos" ], "env": { "SUPOS_API_KEY": "", "SUPOS_API_URL": "", "SUPOS_MQTT_URL": "", "SUPOS_PG_URL": "" } } } }

• Details: <API_URL> should point to your accessible supOS Community Edition endpoint; trials are available here. <API_KEY> is required for authenticated external API access. <MQTT_URL> is determined by inspecting UNS -> MqttBroker -> Listeners for the subscription address. <PG_URL> requires the PostgreSQL connection string, formatted as: postgresql://user:password@host:port/db-name

Crucial Note: The default configuration utilizes npx to fetch and execute the mcp-server-supos package locally, which can sometimes cause issues with environment variable propagation on Windows. Consider the alternatives below for reliability:

Local Service Deployment Alternatives

Select one of the following two deployment strategies:

• Local installation via npm and direct execution via Node

• Installation command

bash npm install mcp-server-supos -g

1. Ascertain the installation path (e.g., for Windows: "C://Users//<USER_NAME>//AppData//Roaming//npm//node_modules//mcp-server-supos//dist//index.js")

2. Update claude_desktop_config.json with the path and restart the client application

{ "mcpServers": { "supos": { "command": "node", "args": [ "C://Users////AppData//Roaming//npm//node_modules//mcp-server-supos//dist//index.js" ], "env": { "SUPOS_API_KEY": "", "SUPOS_API_URL": "", "SUPOS_MQTT_URL": "", "SUPOS_PG_URL": "" } } } }

• Cloning, compiling, and running from source code

• Obtain the source code repository:

bash git clone https://github.com/FREEZONEX/mcp-server-supos.git

1. Install dependencies

bash npm ci

1. Compile the project

bash npm run build

1. Modify claude_desktop_config.json to point to the local build output and restart the client

{ "mcpServers": { "supos": { "command": "node", "args": ["//dist//index.js"], "env": { "SUPOS_API_KEY": "", "SUPOS_API_URL": "", "SUPOS_MQTT_URL": "", "SUPOS_PG_URL": "" } } } }

Summary of Configuration

This completes the tutorial for service deployment. Upon successful setup, the connected client interface will display the available services and their corresponding tools.

Automated Installation via Smithery

For seamless, automated deployment of the supOS MCP Server into Claude Desktop, utilize the Smithery CLI:

bash npx -y @smithery/cli install @FREEZONEX/mcp-server-supos --client claude

Final Commentary

The supOS Community Edition environment now natively incorporates the open-mcp-client utility, initially released by the CopilotKit developers. This integration ensures native support for the mcp-server-supos service and is compliant with the agent TypeScript version.

Licensing Information

This software is distributed under the terms of the Apache License, Version 2.0 (see the included LICENSE file for specifics).

WIKIPEDIA: Cloud computing is "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand," according to ISO. It is commonly referred to as "the cloud".

== Essential Characteristics == In 2011, the National Institute of Standards and Technology (NIST) defined five "fundamental characteristics" critical to cloud systems. Below are the precise definitions provided by NIST:

On-demand self-service: "A consumer is empowered to unilaterally provision computing resources, such as server capacity or network storage, as required and automatically, without necessitating direct human involvement from the service provider for each request." Broad network accessibility: "Capabilities must be accessible over the network utilizing standard protocols, thereby supporting usage across a diverse array of client platforms, whether they are thin or thick (e.g., mobile devices, tablets, laptops, and desktop workstations)." Resource pooling: " The supplier's underlying computing assets are aggregated to serve multiple consumers under a multi-tenant arrangement, where distinct physical and virtual assets are dynamically allocated and reallocated based on fluctuating consumer demand." Rapid scalability: "Resources can be provisioned and decommissioned elastically, sometimes automatically, allowing for swift scaling both outwards and inwards to match fluctuating load. From the consumer's perspective, the available capacity often appears limitless and can be acquired in any volume instantaneously." Measured service: "Cloud infrastructures automatically monitor and optimize resource utilization by employing metering capabilities at an appropriate level of abstraction relative to the service type (e.g., data storage, processing cycles, bandwidth, and active user accounts). Resource consumption must be transparently trackable, controllable, and reportable for both the service provider and the consumer. By 2023, the International Organization for Standardization (ISO) had expanded and formalized this enumeration.

== Historical Context ==

The conceptual roots of utility computing trace back to the 1960s with the popularization of time-sharing concepts via remote job entry (RJE) systems. During this period, the dominant model involved users submitting computational tasks to dedicated operators who ran them on centralized mainframe systems (the 'data center' model). This era was marked by significant R&D into making high-capacity computational power accessible to a broader user base through resource sharing, optimizing the infrastructure stack, and boosting end-user productivity. The term 'cloud' to denote networked, virtualized services originated in 1994, used by General Magic to describe the abstract space accessible by mobile agents within their Telescript framework. This metaphor is attributed to David Hoffman, a communications specialist at General Magic, drawing on established usage in telephony and networking. The phrase 'cloud computing' gained broader recognition in 1996 when Compaq Computer Corporation drafted a strategic business outline for the future of computing and the Internet, aiming to centralize digital services.