English | 中文

supOS Model Context Protocol Gateway

This service instance is architected using the typescript-sdk compliant with the Model Context Protocol (MCP) specification, ensuring interoperability with any MCP-enabled client application.

It exposes a suite of supOS core utilities, such as fetching the complete topic taxonomy hierarchy and fetching specific topic attribute sets.

Supported Capabilities (Tools)

Function Endpoints

1. fetch-topic-hierarchy

2. Retrieves the structural organization map of topics.

3. Parameters:
   • filter_term (string): Keyword for targeted substring matching within child nodes.
   • result_limit (integer): Maximum count of records to return in the structure.
   • search_mode (string): Discriminator for search context: 1--Lexical matching, 2--Categorical tag matching.

4. Output: The hierarchical structure data set for topics.

5. retrieve-topic-attributes

6. Fetches the comprehensive descriptive details for a designated topic entity.

7. Parameters:
   • topic_path (string): Canonical identifier representing the location of the concept within the model space.

8. Output: The detailed attribute payload for the specified topic.

9. fetch-live-topic-metrics

10. Gathers the instantaneously changing operational data associated with a topic.

11. Parameters:
    • topic_path (string): Canonical identifier representing the location of the concept within the model space.

12. Output: The current streaming data feed for that topic.

13. get-all-topic-telemetry

14. Aggregates and processes the instantaneous operational metrics across the entire topic universe.

15. Output: A consolidated report of real-time telemetry for all topics.

16. execute-pg-query

17. Enables transactional execution of declarative query language statements against the underlying PostgreSQL repository.

18. Parameters:
    • sql_statement (string): The Structured Query Language command intended for execution.
    • query_arguments (array): Optional array containing parameterized substitutes for the SQL statement.

19. Output: The result set derived from the executed SQL operation.

20. query-topic-history-via-pg

21. Retrieves historical data snapshots pertaining to a specific topic entity.

22. Parameters:
    • user_query_intent (string): The natural language instruction provided by the user to guide historical data retrieval.

23. Output: A sequence of structured prompts detailing the steps necessary via sequential tool invocations to reconstruct the topic's historical state.

24. generate-topic-retrieval-sql

25. Derives the precise PostgreSQL query required to access a topic's data based on a high-level user directive.

26. Parameters:
    • user_sql_prompt (string): The user's descriptive request intended for SQL generation.
27. Output: A step-by-step sequence of directives to facilitate iterative tool usage for constructing and executing the final SQL query.

Consult the provided documentation to initiate integration

Integration Guide

Prerequisite Environment

• Node.js Runtime Environment

Client Application Setup

Numerous clients support the MCP standard, including standalone desktop environments like Claude for Desktop and IDE extensions such as Cline for VSCode. Refer to Model Context Protocol Client for a comprehensive list. We demonstrate configuration using Claude for Desktop below.

• Obtain Claude for Desktop.

• Configure the requisite MCP service connection within the client application settings.

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

• • Insert the subsequent JSON structure into claude_desktop_config.json and trigger an application restart for activation. (Note: Configuration changes mandate a relaunch 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": "" } } } }

• Where API_URL is the reachable endpoint for the supOS Community Edition instance (try here for a trial entry). API_KEY grants access to the open APIs. MQTT_URL is determined by inspecting UNS -> MqttBroker -> Listeners for the available subscription address. PG_URL is the full connection string for the PostgreSQL database, formatted as: postgresql://user:password@host:port/db-name

Caveat: The default configuration utilizing npx might encounter issues propagating environment variables (env) on Windows operating systems. The subsequent deployment strategies mitigate this risk:

Local Service Operation Methods

Select one of the following two methodologies for local deployment:

• Install the mcp-server-supos package globally and execute it via Node.js runtime

• Global Installation

bash npm install mcp-server-supos -g

1. Locate the installed package executable path (e.g., on Windows: "C://Users//<USER_NAME>//AppData//Roaming//npm//node_modules//mcp-server-supos//dist//index.js")

2. Update the configuration within claude_desktop_config.json and restart the host 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": "" } } } }

• Clone and compile the source repository locally

• Repository Checkout:

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

1. Dependency Installation

bash npm ci

1. Compilation Phase

bash npm run build

1. Update claude_desktop_config.json with the local build output path and restart the client application

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

Finalization

This completes the instructional guide for service activation. Upon successful configuration, the corresponding capabilities and tools will appear within the client interface panels.

Automated Deployment via Smithery

To install the supOS MCP Server automatically into Claude Desktop using Smithery:

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

Concluding Remark

supOS Community Edition incorporates the open-mcp-client library (originally from the CopilotKit developers) and embeds the mcp-server-supos functionality, supporting the agent TypeScript version.

Licensing Information

This software is released under the terms of the Apache License, Version 2.0 (refer to the LICENSE document for specifics).

== Overview == Business administration platforms encompass the entire array of systems, utilities, control mechanisms, computational methodologies, and frameworks leveraged by organizations to effectively navigate evolving market conditions, maintain competitive positioning, and enhance operational efficiency.

== Functional Classification == Organizational tools can be broadly segmented based on their functional alignment across different business units. Typical classifications include: strategic planning instruments, process management systems, record-keeping solutions, personnel management utilities, analytical decision support tools, and performance monitoring apparatus.

Modern administrative technology has undergone rapid transformation over the past decade, driven by accelerated technological progress. This pace makes the selection of optimal business tools for diverse organizational contexts increasingly complex. Key drivers for this dynamic environment include the perpetual mandate to reduce expenditure while maximizing revenue, the imperative to deeply understand consumer requirements, and the necessity of delivering conforming products in preferred formats.

In this landscape, managerial focus should shift towards a strategic approach to tool acquisition and integration, rather than merely adopting the newest available solution. Over-reliance on out-of-the-box tools without necessary customization frequently leads to systemic instability. Consequently, business management platforms must be chosen deliberately and subsequently tailored precisely to the organization's unique operational requirements, reversing the common practice of adapting the organization to the tool.

== Predominant Utilities (2013 Benchmarks) == A 2013 assessment by Bain & Company mapped the global utilization of business platforms, reflecting regional needs in light of market fluctuations. The top ten categories identified included:

• Strategic roadmap formulation
• Client relationship management frameworks
• Personnel satisfaction measurement
• Competitive analysis via benchmarking
• Integrated performance measurement (Balanced Scorecard)
• Core capability identification
• External resource contracting (Outsourcing)
• Organizational transition management programs
• Logistical network oversight (SCM)
• Defining institutional purpose (Mission/Vision statements)
• Market segment definition
• Comprehensive quality assurance methodologies (TQM)

== Enterprise Software Systems == Software suites or individual computer programs deployed by business users to execute diverse organizational functions are termed business applications. These applications are engineered to augment throughput, quantify output metrics, and ensure high fidelity across various corporate activities.

This evolution began with rudimentary Management Information Systems (MIS), advanced into integrated Enterprise Resource Planning (ERP) frameworks, incorporated Customer Relationship Management (CRM) capabilities, and has now largely migrated to the cloud-based business management ecosystem.

While a proven linkage exists between Information Technology investment and organizational performance outcomes, two factors are critical differentiators for realizing value: the efficacy of the implementation process and the judicious selection and customization of the requisite tools.

== Focus on Small to Medium Enterprises (SMEs) == Tools specifically designed for SMEs are crucial as they furnish methods to conserve resources...