# LM Studio Connectors

Local MCP tools for LM Studio:

- DuckDuckGo/metasearch through `ddgs`
- Web scraping and article extraction through `httpx` + Trafilatura
- `yt-dlp` metadata, subtitles, audio, and video downloads
- MFLUX image generation on macOS/Apple Silicon when MFLUX is installed
- Playwright CLI browser automation through `@playwright/cli`

The project is intentionally one MCP server so LM Studio only needs one local entry.

## Install

```bash
cd /absolute/path/to/LMStudioConnectors
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev,browser]"
python -m playwright install chromium
npm install
npx playwright install chromium
```

LM Studio should launch `bin/lmstudio-connectors-mcp`. The wrapper sets
`PYTHONPATH` explicitly and then starts the server from the project virtual
environment.

MFLUX is optional. Install it separately on the Mac that will generate images:

```bash
python -m pip install mflux
```

## LM Studio `mcp.json`

Open LM Studio's MCP settings and add:

```json
{
  "mcpServers": {
    "lmstudio-connectors": {
      "command": "/absolute/path/to/LMStudioConnectors/bin/lmstudio-connectors-mcp",
      "args": []
    }
  }
}
```

The same content is checked in at `lmstudio.mcp.example.json`.

If you install `uv` later, this entry also works:

```json
{
  "mcpServers": {
    "lmstudio-connectors": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/LMStudioConnectors",
        "run",
        "lmstudio-connectors-mcp"
      ]
    }
  }
}
```

## Tools

| Tool | Purpose |
| --- | --- |
| `web_search` | Search the web and return ranked title/URL/snippet results. |
| `web_scrape` | Fetch a page and extract clean Markdown, text, JSON, or HTML. |
| `yt_info` | Return metadata for a video or, when explicitly enabled, a playlist. |
| `yt_subtitles` | Save subtitles/transcripts and return cleaned text. |
| `yt_download` | Download audio or video into the controlled output directory. |
| `mflux_generate` | Generate an image by calling the local MFLUX CLI. |
| `mflux_info` | Read MFLUX metadata from a generated image. |
| `playwright_cli_open` | Open a URL in a named Playwright CLI browser session. |
| `playwright_cli_goto` | Navigate the current Playwright CLI page. |
| `playwright_cli_snapshot` | Capture an accessibility snapshot with element refs. |
| `playwright_cli_action` | Run safe CLI actions like click, fill, press, console, requests, and tabs. |
| `playwright_cli_save` | Save screenshots or PDFs under `outputs/playwright-cli/`. |
| `playwright_cli_close` | Close the named Playwright CLI session. |
| `playwright_cli_health` | Report local Playwright CLI availability. |
| `connector_health` | Report installed optional dependencies and output paths. |

## Playwright CLI

This repo uses Microsoft's `@playwright/cli` package for the CLI-first browser
workflow. The wrapper is `bin/playwright-cli`, and it loads
`.playwright/cli.config.json` from the repo root.

Useful manual commands:

```bash
bin/playwright-cli --help
bin/playwright-cli open https://example.com
bin/playwright-cli snapshot --depth=4
bin/playwright-cli screenshot --filename=outputs/playwright-cli/example.png
bin/playwright-cli close
```

LM Studio can use the same CLI through the `playwright_cli_*` MCP tools exposed
by `lmstudio-connectors`.

## Safety Defaults

- Tools only accept `http` and `https` URLs.
- Localhost, private IPs, loopback, multicast, link-local, and reserved networks are blocked unless `LMSTUDIO_CONNECTORS_ALLOW_PRIVATE_NET=1`.
- Files are written only under `outputs/` or `LMSTUDIO_CONNECTORS_OUTPUT_DIR`.
- yt-dlp playlists are disabled unless the tool call explicitly opts in.
- MFLUX command arguments are built from validated typed fields, not raw shell strings.
- Playwright CLI output is constrained to `outputs/playwright-cli/`, and the MCP
  wrapper only exposes an allowlist of CLI commands/options.

## Useful Environment Variables

| Variable | Default | Purpose |
| --- | --- | --- |
| `LMSTUDIO_CONNECTORS_OUTPUT_DIR` | `./outputs` | Root for all generated files. |
| `LMSTUDIO_CONNECTORS_ALLOW_PRIVATE_NET` | `0` | Allow localhost/private URLs when set to `1`. |
| `LMSTUDIO_CONNECTORS_HTTP_TIMEOUT` | `20` | HTTP fetch timeout in seconds. |
| `LMSTUDIO_CONNECTORS_MAX_RESPONSE_BYTES` | `5000000` | Max web page bytes before extraction. |
| `LMSTUDIO_CONNECTORS_DEFAULT_MAX_CHARS` | `12000` | Default text returned to LM Studio. |
| `LMSTUDIO_CONNECTORS_MFLUX_BIN` | auto-detect | Override MFLUX image generation binary. |
| `LMSTUDIO_CONNECTORS_MFLUX_INFO_BIN` | auto-detect | Override MFLUX metadata binary. |

## Top Next Integrations

1. Playwright MCP for full browser interaction, login-dependent pages, and dynamic apps.
2. Local document/PDF extraction for classroom handouts, Moodle exports, and PDFs.
3. Strict-root filesystem search for local course and code folders.
4. Local vector memory using LM Studio embeddings for durable notes and retrieved context.
5. Moodle/local-service tools for the user's existing course workflows.
6. Optional remote MCPs: Hugging Face, Notion, Linear, Atlassian, Sentry.

## License

MIT. See `LICENSE`. Third-party Python and npm dependencies retain their own
licenses.