@symbo.ls/mcp 1.0.0 → 1.0.4

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(claude mcp remove symbols-mcp)",
+      "Bash(claude mcp add --scope global symbols-mcp /usr/local/bin/symbols-mcp)",
+      "WebFetch(domain:github.com)"
+    ]
+  }
+}

package/README.md

@@ -1,184 +1,80 @@
-# Symbols MCP Server
-
-An MCP (Model Context Protocol) server that exposes the Symbols/DOMQL v3 AI assistant capabilities to any MCP-compatible platform — **Cursor**, **Claude Code**, **Windsurf**, and more.
-
-## Features
-
-### Tools
-| Tool | Description |
-|------|-------------|
-| `generate_component` | Generate a Symbols/DOMQL v3 component from natural language |
-| `generate_page` | Generate a full page with routing support |
-| `generate_project` | Scaffold a complete multi-file Symbols project |
-| `convert_to_symbols` | Convert React/Angular/Vue/HTML to Symbols/DOMQL v3 |
-| `search_symbols_docs` | Search Symbols documentation (vector or local) |
-| `explain_symbols_concept` | Explain any Symbols concept with examples |
-| `review_symbols_code` | Review code for v3 compliance and best practices |
-| `create_design_system` | Generate design system files (colors, spacing, themes, icons) |
-
-### Resources
-| Resource URI | Description |
-|-------------|-------------|
-| `symbols://skills/domql-v3-reference` | Complete DOMQL v3 syntax reference |
-| `symbols://skills/project-structure` | Project folder structure conventions |
-| `symbols://skills/design-direction` | Modern UI/UX design direction |
-| `symbols://skills/migration-guide` | React/Angular/Vue → Symbols migration |
-| `symbols://skills/v2-to-v3-migration` | DOMQL v2 → v3 changes |
-| `symbols://skills/quickstart` | CLI setup and quickstart |
-| `symbols://reference/spacing-tokens` | Spacing token reference table |
-| `symbols://reference/atom-components` | Built-in primitive components |
-| `symbols://reference/event-handlers` | Event handler reference |
-
-### Prompts
-| Prompt | Description |
-|--------|-------------|
-| `symbols_component_prompt` | Template for component generation |
-| `symbols_migration_prompt` | Template for framework migration |
-| `symbols_project_prompt` | Template for project scaffolding |
-| `symbols_review_prompt` | Template for code review |
+# symbols-mcp
+
+mcp-name: io.github.symbo-ls/symbols-mcp
+
+MCP server for [Symbols/DOMQL v3](https://symbols.so) — provides documentation search and framework reference tools for AI coding assistants (Cursor, Claude Code, Windsurf, etc.).
+
+No API keys required. All tools work fully offline using bundled documentation.
 
 ---
 
-## Installation
+## Tools
 
-### Quick Start (No API Keys Required!)
+- **`get_project_rules`** — Returns mandatory Symbols/DOMQL v3 rules. Call this before any code generation task.
+- **`search_symbols_docs`** — Keyword search across all bundled Symbols documentation files.
 
-1. **Clone the repository**:
-```bash
-git clone https://github.com/baronsilver/symbols-mcp-server.git
-cd symbols-mcp-server
-```
+## Resources
 
-2. **Install dependencies**:
-```bash
-pip install uv
-uv sync
-npm i @symbo.ls/cli -g
-smbls create your-project
-```
-IMPORTANT: For now, delete the docs folder inside your project folder after creation
+- `symbols://skills/domql-v3-reference` — Complete DOMQL v3 syntax reference
+- `symbols://skills/project-structure` — Project folder structure and file conventions
+- `symbols://skills/design-direction` — UI/UX design direction
+- `symbols://skills/migration-guide` — React/Angular/Vue → Symbols migration guide
+- `symbols://skills/v2-to-v3-migration` — DOMQL v2 → v3 changes
+- `symbols://skills/quickstart` — CLI quickstart
+- `symbols://reference/spacing-tokens` — Spacing token reference
+- `symbols://reference/atom-components` — Built-in atom components
+- `symbols://reference/event-handlers` — Event handler reference
 
-3. **Configure**:
-```bash
-cp .env.example .env
-# Edit .env and add both:
-# - SYMBOLS_MCP_URL (contact maintainer for public server URL)
-# - LLM_MODEL=google/gemini-3-flash-preview
-```
+## Prompts
 
-## Platform Integration
+- `symbols_component_prompt` — Template for generating a component
+- `symbols_migration_prompt` — Template for migrating framework code
+- `symbols_project_prompt` — Template for scaffolding a full project
+- `symbols_review_prompt` — Template for reviewing Symbols code
 
-### Claude Code
+---
+
+## Installation
 
 ```bash
-claude mcp add symbols-mcp -- uv run --directory C:\repos\symbols-mcp-server symbols-mcp
+pip install symbols-mcp
 ```
 
-Or manually edit `~/UserName/.claude.json`:
-```json
-{
-  "mcpServers": {
-    "symbols-mcp": {
-      "command": "python",
-      "args": [
-        "-m",
-        "uv",
-        "run",
-        "--directory",
-        "C:\\repos\\symbols-mcp-server",
-        "symbols-mcp"
-      ]
-    }
-  }
-}
+Or with `uv`:
+
+```bash
+uvx symbols-mcp
 ```
 
-### Cursor
+## Configuration
 
-Add to your Cursor MCP settings (`.cursor/mcp.json` in your project or global settings):
+Add to your MCP client config (e.g. `mcp.json`):
 
 ```json
 {
   "mcpServers": {
-    "symbols-mcp": {
-      "command": "python",
-      "args": [
-        "-m",
-        "uv",
-        "run",
-        "--directory",
-        "C:\\repos\\symbols-mcp-server",
-        "symbols-mcp"
-      ]
+    "symbols": {
+      "command": "uvx",
+      "args": ["symbols-mcp"]
     }
   }
 }
 ```
 
-### Windsurf
+### Custom skills directory
 
-Add to `~/.codeium/windsurf/mcp_config.json`:
+To point at a different skills folder:
 
 ```json
 {
   "mcpServers": {
-    "symbols-mcp": {
-      "command": "python",
-      "args": [
-        "-m",
-        "uv",
-        "run",
-        "--directory",
-        "C:\\repos\\symbols-mcp-server",
-        "symbols-mcp"
-      ]
+    "symbols": {
+      "command": "uvx",
+      "args": ["symbols-mcp"],
+      "env": {
+        "SYMBOLS_SKILLS_DIR": "/path/to/your/skills"
+      }
     }
   }
 }
 ```
-
-
-## Development
-
-Restart your platforms after updating the MCP settings. Once loaded, it should automatically run the MCP. Ask your AI to do the quick test with the MCP to see if it works properly.
-
----
-
-## Environment Variables
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `OPENROUTER_API_KEY` | **Yes** | — | API key for OpenRouter (powers AI generation) |
-| `SUPABASE_URL` | No | — | Supabase project URL for vector search |
-| `SUPABASE_KEY` | No | — | Supabase service role key |
-| `LLM_MODEL` | No | `openai/gpt-4.1-mini` | AI model to use via OpenRouter |
-| `SYMBOLS_SKILLS_DIR` | No | `./symbols_mcp/skills` | Path to skills markdown files |
-
----
-
-## Architecture
-
-```
-symbols-mcp-server/
-├── pyproject.toml              # Project config and dependencies
-├── .env.example                # Environment variable template
-├── README.md                   # This file
-└── symbols_mcp/
-    ├── __init__.py
-    ├── server.py               # MCP server with tools, resources, prompts
-    └── skills/                 # Bundled Symbols knowledge base
-        ├── CLAUDE.md           # DOMQL v3 complete reference
-        ├── SYMBOLS_LOCAL_INSTRUCTIONS.md  # Project structure rules
-        ├── DESIGN_DIRECTION.md # UI/UX design direction
-        ├── MIGRATE_TO_SYMBOLS.md # Framework migration guide
-        ├── DOMQL_v2-v3_MIGRATION.md # v2→v3 changes
-        └── QUICKSTART.md       # CLI quickstart
-```
-
-The server reads skills files at startup and uses them as context for all AI-powered tools.
-When Supabase is configured, the `search_symbols_docs` tool also queries the vector database
-for additional documentation matches.
-
----
-
-

package/bin/symbols-mcp.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+const { spawn } = require('child_process')
+const { execSync } = require('child_process')
+
+let cmd, args
+
+try {
+  execSync('uvx --version', { stdio: 'ignore' })
+  cmd = 'uvx'
+  args = ['symbols-mcp']
+} catch {
+  cmd = 'python3'
+  args = ['-m', 'symbols_mcp.server']
+}
+
+const child = spawn(cmd, args, { stdio: 'inherit' })
+child.on('exit', code => process.exit(code ?? 0))

package/generate-mcpb.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -e
+
+# Install mcpb CLI if needed
+if ! command -v mcpb &> /dev/null; then
+  echo "Installing mcpb..."
+  npm install -g @modelcontextprotocol/mcpb
+fi
+
+# Sync version from pyproject.toml into manifest.json
+VERSION=$(grep '^version' pyproject.toml | head -1 | sed 's/version = "\(.*\)"/\1/')
+sed -i '' "s/\"version\": \".*\"/\"version\": \"$VERSION\"/" manifest.json
+
+# Pack the .mcpb bundle
+mcpb pack
+
+echo "Generated symbols-mcp-${VERSION}.mcpb"

package/manifest.json

@@ -0,0 +1,64 @@
+{
+  "manifest_version": "0.3",
+  "name": "symbols-mcp",
+  "display_name": "Symbols MCP",
+  "version": "1.0.3",
+  "description": "MCP server for Symbols/DOMQL v3 — documentation search and framework reference",
+  "author": {
+    "name": "Symbols",
+    "url": "https://symbols.so"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/symbo-ls/symbols-mcp.git"
+  },
+  "homepage": "https://symbols.so",
+  "documentation": "https://github.com/symbo-ls/symbols-mcp",
+  "support": "https://github.com/symbo-ls/symbols-mcp/issues",
+  "keywords": ["symbols", "domql", "mcp", "design-system", "ai"],
+  "license": "MIT",
+  "server": {
+    "type": "python",
+    "mcp_config": {
+      "command": "uvx",
+      "args": ["symbols-mcp"]
+    }
+  },
+  "tools": [
+    {
+      "name": "get_project_rules",
+      "description": "Returns mandatory Symbols/DOMQL v3 rules. Call this first before any code generation."
+    },
+    {
+      "name": "search_symbols_docs",
+      "description": "Search the Symbols documentation knowledge base for relevant information."
+    }
+  ],
+  "prompts": [
+    {
+      "name": "symbols_component_prompt",
+      "description": "Generate a Symbols/DOMQL v3 component",
+      "arguments": ["description", "component_name"]
+    },
+    {
+      "name": "symbols_migration_prompt",
+      "description": "Migrate React/Angular/Vue code to Symbols/DOMQL v3",
+      "arguments": ["source_framework"]
+    },
+    {
+      "name": "symbols_project_prompt",
+      "description": "Scaffold a complete Symbols project",
+      "arguments": ["description"]
+    },
+    {
+      "name": "symbols_review_prompt",
+      "description": "Review Symbols/DOMQL code for v3 compliance"
+    }
+  ],
+  "compatibility": {
+    "platforms": ["darwin", "win32", "linux"],
+    "runtimes": {
+      "python": ">=3.10"
+    }
+  }
+}

package/package.json

@@ -1,20 +1,15 @@
 {
   "name": "@symbo.ls/mcp",
-  "version": "1.0.0",
-  "description": "An MCP (Model Context Protocol) server that exposes the Symbols/DOMQL v3 AI assistant capabilities to any MCP-compatible platform — **Cursor**, **Claude Code**, **Windsurf**, and more.",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "1.0.4",
+  "description": "MCP server for Symbols/DOMQL v3 — documentation search and framework reference",
+  "mcpName": "io.github.symbo-ls/symbols-mcp",
+  "bin": {
+    "symbols-mcp": "./bin/symbols-mcp.js"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/symbo-ls/symbols-mcp-server.git"
+    "url": "https://github.com/symbo-ls/symbols-mcp.git"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "bugs": {
-    "url": "https://github.com/symbo-ls/symbols-mcp-server/issues"
-  },
-  "homepage": "https://github.com/symbo-ls/symbols-mcp-server#readme"
+  "keywords": ["mcp", "symbols", "domql", "ai", "claude"],
+  "license": "MIT"
 }

package/publish.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+set -e
+
+# Usage: ./publish.sh [patch|minor|major|x.y.z]
+# Stores PyPI token in .pypi_token (gitignored)
+
+BUMP=${1:-patch}
+
+# Read current version from pyproject.toml
+CURRENT=$(grep '^version' pyproject.toml | head -1 | sed 's/version = "\(.*\)"/\1/')
+IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
+
+case "$BUMP" in
+  patch)   NEW="$MAJOR.$MINOR.$((PATCH + 1))" ;;
+  minor)   NEW="$MAJOR.$((MINOR + 1)).0" ;;
+  major)   NEW="$((MAJOR + 1)).0.0" ;;
+  *.*.*)   NEW="$BUMP" ;;
+  *)       echo "Usage: $0 [patch|minor|major|x.y.z]"; exit 1 ;;
+esac
+
+echo "Bumping $CURRENT → $NEW"
+
+# Update versions
+sed -i '' "s/^version = \"$CURRENT\"/version = \"$NEW\"/" pyproject.toml
+sed -i '' "s/\"version\": \"$CURRENT\"/\"version\": \"$NEW\"/g" server.json
+sed -i '' "s/\"version\": \"$CURRENT\"/\"version\": \"$NEW\"/" package.json
+
+# Build Python package
+rm -f dist/symbols_mcp-${CURRENT}*
+uv build
+
+# Publish to PyPI
+if [ -f .pypi_token ]; then
+  TOKEN=$(cat .pypi_token)
+else
+  read -rsp "PyPI token: " TOKEN; echo
+fi
+uv publish --token "$TOKEN"
+
+# Publish to npm
+chmod +x bin/symbols-mcp.js
+npm publish --access public
+
+# Generate .mcpb bundle
+./generate-mcpb.sh
+
+# Publish to MCP registry
+echo "Publishing to MCP registry..."
+mcp-publisher publish
+
+echo "Done! Published symbols-mcp $NEW"

package/pyproject.toml

@@ -1,17 +1,11 @@
 [project]
-name = "symbols-mcp-server"
-version = "1.0.0"
-description = "MCP server for the Symbols AI assistant - provides DOMQL/Symbols code generation, migration, and documentation tools"
+name = "symbols-mcp"
+version = "1.0.4"
+description = "MCP server for Symbols/DOMQL v3 — documentation search and framework reference"
+readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
     "mcp[cli]>=1.9.0",
-    "httpx[http2]>=0.27.0",
-    "python-dotenv>=1.0.0",
-    "pydantic>=2.0.0",
-    "fastapi>=0.104.0",
-    "uvicorn[standard]>=0.24.0",
-    "flask>=3.0.0",
-    "flask-cors>=4.0.0",
 ]
 
 [project.scripts]

package/server.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.symbo-ls/symbols-mcp",
+  "version": "1.0.4",
+  "title": "Symbols MCP",
+  "description": "MCP server for Symbols/DOMQL v3 — documentation search and framework reference",
+  "repository": {
+    "url": "https://github.com/symbo-ls/symbols-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "symbols-mcp",
+      "version": "1.0.4",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      }
+    },
+    {
+      "registryType": "npm",
+      "identifier": "@symbo.ls/mcp",
+      "version": "1.0.4",
+      "runtimeHint": "npx",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

package/symbols_mcp/__init__.py

@@ -1 +1 @@
-# Symbols MCP Server
+# Symbols MCP