Scaffold OBSMCP: local MCP tool + FastAPI backend + React dashboard

.dockerignore

@@ -0,0 +1,11 @@
+.git
+.github
+.venv
+frontend/node_modules
+frontend/dist
+server/obsmcp_server/frontend_dist
+**/__pycache__
+**/*.pyc
+.obsmcp
+*.db
+.env

.env.example

@@ -0,0 +1,9 @@
+# OBSMCP server configuration
+# Leave OBSMCP_API_TOKEN blank to disable auth (local mode).
+OBSMCP_API_TOKEN=
+OBSMCP_DB_PATH=~/.obsmcp/data/obsmcp.db
+OBSMCP_HOST=0.0.0.0
+OBSMCP_PORT=8000
+
+# Optional: Anthropic API key for semantic descriptions
+ANTHROPIC_API_KEY=

.gitignore

@@ -1,22 +1,49 @@
-.venv/
+# Python
 __pycache__/
-*.pyc
-*.pyo
+*.py[cod]
+*.egg-info/
+.eggs/
+.venv/
+venv/
+env/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg
+
+# Node / frontend
+node_modules/
+frontend/dist/
+server/obsmcp_server/frontend_dist/
+.npm/
+.pnpm-store/
+.vite/
+
+# OBSMCP local data / configs (never commit!)
+.obsmcp/
+*.db
+*.db-journal
+*.sqlite
 *.sqlite3
-*.sqlite3-shm
-*.sqlite3-wal
+obsmcp.db*
+
+# IDE / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+
+# Logs
 *.log
-*.zip
-/backups/
-/.context/
-/.pytest_cache/
-/.tmp-tests/
-/.tmp-caveman/
-/data/
-/hub/
-/logs/
-/.obsmcp-link.json
-/obsidian/
-/projects/
-/registry/
-/workspace/
+logs/

.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+Thanks for helping improve OBSMCP!
+
+## Local setup
+
+```bash
+python -m pip install -e ".[dev]"
+pre-commit install
+
+cd frontend && npm install
+```
+
+## Running the stack locally
+
+```bash
+# Terminal 1 — backend
+OBSMCP_API_TOKEN=dev obsmcp-server
+
+# Terminal 2 — frontend
+cd frontend
+npm run dev     # http://localhost:5173 (proxies /api and /ws to 8000)
+
+# Terminal 3 — local agent (writes to the running backend)
+./start.sh      # first run prompts for config
+```
+
+## Code style
+
+- **Python:** formatted + linted by `ruff` (see `pyproject.toml`). 100-char lines.
+- **TypeScript:** strict mode on; lint with `npm run lint`.
+- **No ORMs.** Stick to raw `sqlite3`.
+- **Every mutation must emit an SSE event** via `broadcast_event(...)`. See existing routers.
+
+## Adding a new entity
+
+1. Extend `server/obsmcp_server/schema.sql`.
+2. Add a router under `server/obsmcp_server/routers/`, hook it up in `main.py`, and emit events.
+3. Add a TypeScript type in `frontend/src/api/types.ts`.
+4. Map event types → query keys in `frontend/src/events/EventBus.ts`.
+5. Add a page under `frontend/src/pages/`, wire it into `App.tsx` and the sidebar nav.
+6. Mirror the write path in `tool/obsmcp/client/http_client.py` so agents can use it offline-first.
+7. Add tests in `server/tests/` and `tool/tests/`.
+
+## Tests
+
+```bash
+pytest -q                 # backend + tool
+cd frontend && npm run typecheck && npm run build
+```
+
+Run all three locally before opening a PR — this project intentionally has no CI/GitHub Actions.

Dockerfile

@@ -0,0 +1,35 @@
+# syntax=docker/dockerfile:1.6
+
+# ---------- frontend build ----------
+FROM node:20-alpine AS frontend
+WORKDIR /app/frontend
+COPY frontend/package.json frontend/package-lock.json* ./
+RUN npm install --no-audit --no-fund
+COPY frontend .
+RUN npm run build
+
+# ---------- backend image ----------
+FROM python:3.12-slim AS backend
+WORKDIR /app
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential git curl && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml README.md ./
+COPY tool tool
+COPY server server
+# Bring the built frontend into the package's static dir
+COPY --from=frontend /app/server/obsmcp_server/frontend_dist server/obsmcp_server/frontend_dist
+
+RUN pip install --upgrade pip && pip install .
+
+ENV OBSMCP_HOST=0.0.0.0 \
+    OBSMCP_PORT=8000
+
+EXPOSE 8000
+CMD ["obsmcp-server"]

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 nikzdevz
+Copyright (c) 2026 OBSMCP Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal