SEMOSS Vibe Engineering Setup & Sync Guide

This workspace contains the local assets for a SEMOSS project (project ID stored in semoss_config/config.json). The "Vibe Engineering" setup described below prepares your environment, keeps credentials in sync, and pushes assets back to SEMOSS. All host-specific values (base_url, api_module_url, web_module_url) live in semoss_config/config.json so the guide stays environment agnostic.

Prerequisites

1. Python 3.13 (Windows Store py -3.13)
   The sync script relies on the system-wide 3.13 interpreter. Other versions may not have the SEMOSS SDK available.
2. SEMOSS Python SDK (ai_server)
   Install the wheel published on PyPI as ai-server-sdk so from ai_server import ServerClient succeeds in scripts/semoss_asset_sync.py. Run py -3.13 -m pip install ai-server-sdk (or upgrade with --upgrade) to ensure the package lands in the Python 3.13 site-packages that the sync script uses.
3. Node.js + npx
   Required only to interact with remote MCP tools (already configured through .vscode/mcp.json).
4. Access + Secret Keys for SEMOSS
   These are the bearer credentials inserted into .vscode/mcp.json and used by the sync utilities. Treat them as secrets. Generate or rotate tokens through the platform's profile settings (Settings ▸ My Profile) available under your base_url instance.

requests is optional. If it is unavailable, the sync script automatically falls back to Python's standard library networking stack.

Configuration Files

File	Purpose
.vscode/mcp.json	Wires VS Code MCP to the SEMOSS remote tools. Update it through scripts/semoss_asset_sync.py configure-local whenever keys rotate.
semoss_config/config.json	Stores project metadata (project ID, base_url, api_module_url, web_module_url, creation timestamp). Keep this committed so collaborators share the same target project.

Workflow

1. Refresh credentials (when needed)

   • Run the local config helper to update .vscode/mcp.json and semoss_config/config.json in one pass: py -3.13 scripts/semoss_asset_sync.py configure-local --access-key <access_key> --secret-key <secret_key> --base-url <base_url> --api-module-url <api_module_url> --web-module-url <web_module_url> --project-id <project_id>
   • Add --is-mcp for MCP-enabled apps or --is-not-mcp for non-MCP apps. Use --module <value> only when you need a module other than app.
   • Reopen VS Code or run Developer: Reload Window so MCP picks up the change.

2. Ensure local config matches the remote project

   • Confirm the helper wrote the correct project_id and URLs.
   • Re-run the helper whenever those values change instead of editing the files by hand.

3. Upload assets to SEMOSS

   • Run the sync script with the Python launcher to guarantee the 3.13 interpreter:
     py -3.13 scripts/semoss_asset_sync.py upload <path-to-local-file>

   • The script will:

     1. Prompt before deleting any existing remote file.
     2. Back up the remote asset locally under temp/semoss_backups/.
     3. Upload the new file via the SEMOSS SDK.
     4. Publish the project so the change is visible.
     5. If the project is MCP-enabled and py/mcp_driver.py exists, remind you that MakePythonMCP is optional rather than running it automatically.

   • Example (already used for the config file):
     py -3.13 scripts/semoss_asset_sync.py upload semoss_config/config.json

   • To explicitly ask SEMOSS to generate py_mcp.json, run: py -3.13 scripts/semoss_asset_sync.py make-python-mcp

   • If you do not want to run the reactor, you can create or maintain mcp/mcp.json yourself.

4. Download from SEMOSS (optional)

   • Use the sync-from-remote command to pull portal assets to your workspace:
     py -3.13 scripts/semoss_asset_sync.py sync-from-remote version/assets/portals --overwrite

5. Portal URL

   • Once assets are in place, the app is served via <base_url><web_module_url>/packages/client/dist/#/app/cd48cd48-0710-47ff-a3e4-95bed9dd03df/view. Substitute the values from semoss_config/config.json for your target environment.

Troubleshooting

• ModuleNotFoundError: ai_server — Confirm the SEMOSS Python SDK is installed for Python 3.13. Re-run the upload command afterward.
• Invalid credentials — Double-check the bearer token entries and ensure there are no spaces between Bearer and the access/secret pair.
• Network download issues — The script falls back to Python's urllib if requests is unavailable, but a strict firewall may still block access. Verify that your configured base_url host is reachable from this machine.

Keep secrets out of version control, and rotate the access/secret pair immediately if it is ever exposed.

Working with this project

git clone this project first. Once done, change the name of the project, that is the project name you will be using for your application or agent. Please dont call your app vibe_setup_vscode.