sv-mcp 0.2.0__tar.gz

sv_mcp-0.2.0/.env.example

@@ -0,0 +1,13 @@
+# stdio mode (default) - local, single-user
+SV_API_KEY=
+
+# http mode - hosted, multi-user OAuth (set SV_MCP_TRANSPORT=http to enable)
+SV_MCP_TRANSPORT=stdio
+SV_MCP_OAUTH_CLIENT_SECRET=
+SV_MCP_HOST=0.0.0.0
+SV_MCP_PORT=8080
+
+# Optional - both already default to production; only override for a
+# non-default deployment (e.g. testing against a dev SEOB instance)
+# SEOB_BASE_URL=
+# SV_MCP_BASE_URL=

sv_mcp-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish Python package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+
+      - name: Install build
+        run: python -m pip install --upgrade build
+
+      - name: Build wheel and source distribution
+        run: python -m build
+
+      - name: Store distributions
+        uses: actions/upload-artifact@v5
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

sv_mcp-0.2.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Secrets and local config
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.token
+config.json
+.sv/
+
+# OS/editor
+.DS_Store
+.idea/
+.vscode/

sv_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.2.0
+
+First release on PyPI and the MCP Registry.
+
+- Every tool now has a human-readable title and MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`). Tools that save work to the SV account (`prose`, `geogptaudit`, `seogptcompare`, `seogptmapping`, `preliminaryaudit`) are marked as not read-only.
+- Requires sv-cli 0.8.0, which retries automatically when the SV API rate limit (1 request per second per API key) is reached.
+- Removed `seo-image` from the MCP tool list. AI image generation stays available through the SV API and SV CLI.
+- Rewrote tool descriptions to state what each tool does and when to use it, without model-directed instructions.
+- Tool errors now return the SV API's own message, field and error code, with a suggested next step, instead of raw JSON.
+- Integer option fields are sent as a `minimum`/`maximum` range instead of a full list, reducing the size of the tool list by about a third.
+- Added LICENSE, SECURITY.md, CONTRIBUTING.md and CODE_OF_CONDUCT.md.
+
+## 0.1.0
+
+- Initial MCP server built on the sv-cli core library: stdio mode with `SV_API_KEY`, and hosted Streamable HTTP mode with OAuth.
+- Tool families generated from the live SV API definitions, plus `get_task_status` and `get_task_result` for async tasks.
+- `seogpt2` exposed as `prose`.
+- Calls identify themselves to the SV API as MCP clients for usage tracking.

sv_mcp-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Code of Conduct
+
+This project follows the Contributor Covenant spirit: be respectful, constructive, and inclusive.
+
+Unacceptable behavior includes harassment, threats, discriminatory language, or publishing private information. Maintainers may remove comments, issues, commits, or contributors that violate these expectations.

sv_mcp-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+Thanks for contributing to SV MCP.
+
+## Development setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+```
+
+## Guidelines
+
+- SV MCP is a thin layer over the [sv-cli](https://github.com/seovendorco/sv-cli) core library. Request handling, validation, auth resolution and async-task handling live there; keep them there.
+- Tool input schemas are generated from the live SV API definitions. Don't hand-write schemas.
+- Every exposed tool needs a hand-written description in `TOOL_DESCRIPTIONS` (`src/sv_mcp/tool_registry.py`). Describe what the tool does and when to use it, in plain factual terms. Don't add instructions that push the model to prefer a tool, and no marketing language — the tests reject both.
+- Do not hardcode API keys or real customer data in examples, fixtures, tests, or docs.
+- Add tests for schema generation, tool registration, error handling and task behavior changes.
+
+## Pull requests
+
+Before opening a PR:
+
+```bash
+pytest
+python -m build
+```
+
+Describe user-facing behavior, backward compatibility, and any change to the tool list.

sv_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SV MCP 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sv_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: sv-mcp
+Version: 0.2.0
+Summary: MCP server for the SV API: SEO and GEO tools for Claude and other MCP clients.
+Project-URL: Homepage, https://seovendor.co/api/mcp
+Project-URL: Repository, https://github.com/seovendorco/sv-mcp
+Project-URL: Issues, https://github.com/seovendorco/sv-mcp/issues
+Project-URL: Changelog, https://github.com/seovendorco/sv-mcp/blob/main/CHANGELOG.md
+Author: SV MCP Contributors
+License: MIT
+License-File: LICENSE
+Keywords: claude,geo,mcp,mcp-server,model-context-protocol,seo,sv
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=3.4
+Requires-Dist: sv-cli>=0.8.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SV MCP
+
+<!-- mcp-name: co.seovendor/sv-mcp -->
+
+SV MCP is the [Model Context Protocol](https://modelcontextprotocol.io) server for the SV API. It gives Claude, Cursor, VS Code, Windsurf and other MCP clients SV's SEO and GEO tools: keyword research, page audits, AI-visibility (GEO) audits, competitor analysis and content generation.
+
+It is built on the same core library as [SV CLI](https://github.com/seovendorco/sv-cli), so both behave the same way against the SV API.
+
+- **Server URL:** `https://mcp.seovendor.co`
+- **Transport:** Streamable HTTP
+- **Auth:** OAuth 2.1 — sign in with your SV account; your API key stays on the server
+- **Docs:** https://seovendor.co/api/mcp
+- **Free API key:** https://access.seovendor.co/signup
+
+## Connect
+
+### Claude.ai and Claude Desktop
+
+1. Open **Customize → Connectors**.
+2. Click **+ → Add custom connector**.
+3. Paste `https://mcp.seovendor.co` and click **Add**.
+4. Click **Connect** and sign in to SV to approve access.
+
+On Team and Enterprise plans, an Owner first adds the connector under **Organization settings → Connectors**; members then connect it themselves.
+
+### Claude Code
+
+```bash
+claude mcp add --transport http sv-mcp https://mcp.seovendor.co
+```
+
+### Cursor (`~/.cursor/mcp.json`)
+
+```json
+{ "mcpServers": { "sv-mcp": { "url": "https://mcp.seovendor.co" } } }
+```
+
+### VS Code (`.vscode/mcp.json`)
+
+```json
+{ "servers": { "sv-mcp": { "type": "http", "url": "https://mcp.seovendor.co" } } }
+```
+
+### Windsurf (`~/.codeium/windsurf/mcp_config.json`)
+
+```json
+{ "mcpServers": { "sv-mcp": { "serverUrl": "https://mcp.seovendor.co" } } }
+```
+
+### Clients that only support stdio
+
+```json
+{ "mcpServers": { "sv-mcp": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.seovendor.co"] } } }
+```
+
+## Tools
+
+| Tool | What it does | Mode |
+|---|---|---|
+| `better-keywords` | Keyword research: search volume, CPC, competition and intent | Sync |
+| `content-quality` | Scores a page's content quality (E-E-A-T) for a keyword | Sync |
+| `content-transformer` | Rewrites or reformats supplied text into a content type | Sync |
+| `core-analysis` | On-page SEO analysis of a URL | Sync |
+| `insight-igniter` | Entities and topics AI engines associate with a website | Sync |
+| `preliminaryaudit` | Quick automated SEO health score for a URL | Sync |
+| `ranklens` | How a site ranks across repeated AI-engine queries, and competitors | Sync |
+| `seogpt` | Short-form SEO text such as meta titles and descriptions | Sync |
+| `topical-authority` | Topical content plan for a keyword | Sync |
+| `top-competitors` | Top-ranking competitor URLs for a keyword | Sync |
+| `marketplace-services` | Searches SV's catalog of purchasable services | Sync |
+| `geogptaudit` | GEO audit: visibility in AI-generated answers for given entities | Async |
+| `prose` | Writes a long-form article or blog post | Async |
+| `seogptcompare` | Compares a URL against its top competitors for a keyword | Async |
+| `seogptmapping` | Maps keywords to the most relevant pages on a domain | Async |
+| `get_task_status` | Checks the status of an async task | — |
+| `get_task_result` | Fetches the result of a finished async task | — |
+
+**Async tools** return a `task_id` straight away; follow up with `get_task_status` / `get_task_result`, or pass `wait: true` to wait up to 45 seconds for the result in the same call.
+
+**Points:** successful tool calls use points from your SV account. Failed calls, and checking on or fetching a task, don't.
+
+**Rate limit:** the SV API accepts 1 request per second per API key. SV MCP retries automatically when it hits the limit, so this is normally invisible.
+
+## Run locally (stdio)
+
+For a single user on their own machine, run the server locally with your SV API key:
+
+```bash
+pip install sv-mcp
+export SV_API_KEY=your-key
+sv-mcp
+```
+
+Example client entry, using [uv](https://docs.astral.sh/uv/) so nothing needs installing first:
+
+```json
+{ "mcpServers": { "sv-mcp": { "command": "uvx", "args": ["sv-mcp"], "env": { "SV_API_KEY": "your-key" } } } }
+```
+
+## Hosted HTTP mode
+
+`SV_MCP_TRANSPORT=http` runs the multi-user OAuth deployment behind `https://mcp.seovendor.co`. It authenticates against SV's own account system and needs an OAuth client secret registered there, so it is intended for SV's hosted deployment. See `.env.example` for the settings.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Privacy
+
+See the SV privacy policy: https://seovendor.co/privacy-policy/
+
+## Security
+
+See [SECURITY.md](SECURITY.md). Report vulnerabilities to ask@seovendor.co.
+
+## License
+
+[MIT](LICENSE)

sv_mcp-0.2.0/README.md

@@ -0,0 +1,125 @@
+# SV MCP
+
+<!-- mcp-name: co.seovendor/sv-mcp -->
+
+SV MCP is the [Model Context Protocol](https://modelcontextprotocol.io) server for the SV API. It gives Claude, Cursor, VS Code, Windsurf and other MCP clients SV's SEO and GEO tools: keyword research, page audits, AI-visibility (GEO) audits, competitor analysis and content generation.
+
+It is built on the same core library as [SV CLI](https://github.com/seovendorco/sv-cli), so both behave the same way against the SV API.
+
+- **Server URL:** `https://mcp.seovendor.co`
+- **Transport:** Streamable HTTP
+- **Auth:** OAuth 2.1 — sign in with your SV account; your API key stays on the server
+- **Docs:** https://seovendor.co/api/mcp
+- **Free API key:** https://access.seovendor.co/signup
+
+## Connect
+
+### Claude.ai and Claude Desktop
+
+1. Open **Customize → Connectors**.
+2. Click **+ → Add custom connector**.
+3. Paste `https://mcp.seovendor.co` and click **Add**.
+4. Click **Connect** and sign in to SV to approve access.
+
+On Team and Enterprise plans, an Owner first adds the connector under **Organization settings → Connectors**; members then connect it themselves.
+
+### Claude Code
+
+```bash
+claude mcp add --transport http sv-mcp https://mcp.seovendor.co
+```
+
+### Cursor (`~/.cursor/mcp.json`)
+
+```json
+{ "mcpServers": { "sv-mcp": { "url": "https://mcp.seovendor.co" } } }
+```
+
+### VS Code (`.vscode/mcp.json`)
+
+```json
+{ "servers": { "sv-mcp": { "type": "http", "url": "https://mcp.seovendor.co" } } }
+```
+
+### Windsurf (`~/.codeium/windsurf/mcp_config.json`)
+
+```json
+{ "mcpServers": { "sv-mcp": { "serverUrl": "https://mcp.seovendor.co" } } }
+```
+
+### Clients that only support stdio
+
+```json
+{ "mcpServers": { "sv-mcp": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.seovendor.co"] } } }
+```
+
+## Tools
+
+| Tool | What it does | Mode |
+|---|---|---|
+| `better-keywords` | Keyword research: search volume, CPC, competition and intent | Sync |
+| `content-quality` | Scores a page's content quality (E-E-A-T) for a keyword | Sync |
+| `content-transformer` | Rewrites or reformats supplied text into a content type | Sync |
+| `core-analysis` | On-page SEO analysis of a URL | Sync |
+| `insight-igniter` | Entities and topics AI engines associate with a website | Sync |
+| `preliminaryaudit` | Quick automated SEO health score for a URL | Sync |
+| `ranklens` | How a site ranks across repeated AI-engine queries, and competitors | Sync |
+| `seogpt` | Short-form SEO text such as meta titles and descriptions | Sync |
+| `topical-authority` | Topical content plan for a keyword | Sync |
+| `top-competitors` | Top-ranking competitor URLs for a keyword | Sync |
+| `marketplace-services` | Searches SV's catalog of purchasable services | Sync |
+| `geogptaudit` | GEO audit: visibility in AI-generated answers for given entities | Async |
+| `prose` | Writes a long-form article or blog post | Async |
+| `seogptcompare` | Compares a URL against its top competitors for a keyword | Async |
+| `seogptmapping` | Maps keywords to the most relevant pages on a domain | Async |
+| `get_task_status` | Checks the status of an async task | — |
+| `get_task_result` | Fetches the result of a finished async task | — |
+
+**Async tools** return a `task_id` straight away; follow up with `get_task_status` / `get_task_result`, or pass `wait: true` to wait up to 45 seconds for the result in the same call.
+
+**Points:** successful tool calls use points from your SV account. Failed calls, and checking on or fetching a task, don't.
+
+**Rate limit:** the SV API accepts 1 request per second per API key. SV MCP retries automatically when it hits the limit, so this is normally invisible.
+
+## Run locally (stdio)
+
+For a single user on their own machine, run the server locally with your SV API key:
+
+```bash
+pip install sv-mcp
+export SV_API_KEY=your-key
+sv-mcp
+```
+
+Example client entry, using [uv](https://docs.astral.sh/uv/) so nothing needs installing first:
+
+```json
+{ "mcpServers": { "sv-mcp": { "command": "uvx", "args": ["sv-mcp"], "env": { "SV_API_KEY": "your-key" } } } }
+```
+
+## Hosted HTTP mode
+
+`SV_MCP_TRANSPORT=http` runs the multi-user OAuth deployment behind `https://mcp.seovendor.co`. It authenticates against SV's own account system and needs an OAuth client secret registered there, so it is intended for SV's hosted deployment. See `.env.example` for the settings.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Privacy
+
+See the SV privacy policy: https://seovendor.co/privacy-policy/
+
+## Security
+
+See [SECURITY.md](SECURITY.md). Report vulnerabilities to ask@seovendor.co.
+
+## License
+
+[MIT](LICENSE)

sv_mcp-0.2.0/SECURITY.md

@@ -0,0 +1,27 @@
+# Security Policy
+
+## Reporting vulnerabilities
+
+Please do not open public issues for security vulnerabilities. Report suspected vulnerabilities privately to **ask@seovendor.co**.
+
+Include:
+
+- Affected version, commit, or the hosted server URL
+- Reproduction steps
+- Impact
+- Any suggested fix
+
+## How credentials are handled
+
+- **Hosted server (`https://mcp.seovendor.co`):** clients authenticate with OAuth. The user's SV API key is resolved on the server for each request and is never returned to the MCP client or the AI host. Resolved keys are cached in server memory for up to 5 minutes.
+- **Local stdio mode:** the server reads the key from the `SV_API_KEY` environment variable of the process that launches it.
+
+## API-key safety
+
+- Never commit API keys, `.env` files, or OAuth client secrets.
+- Do not paste real keys into issues, logs, screenshots, examples, or tests.
+- Keep `SV_MCP_OAUTH_CLIENT_SECRET` in your process manager or secret store, not in the repository.
+
+## Supported versions
+
+Security fixes target the latest released version and the hosted server.

sv_mcp-0.2.0/glama.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": ["shyamthaker", "jim-seovendor"]
+}

sv_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sv-mcp"
+version = "0.2.0"
+description = "MCP server for the SV API: SEO and GEO tools for Claude and other MCP clients."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+  {name = "SV MCP Contributors"}
+]
+keywords = ["mcp", "mcp-server", "model-context-protocol", "seo", "geo", "claude", "sv"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+  "sv-cli>=0.8.0",  # 0.8.0 adds the HTTP 429 retry the SV API rate limit needs
+  "fastmcp>=3.4",
+]
+
+[project.urls]
+Homepage = "https://seovendor.co/api/mcp"
+Repository = "https://github.com/seovendorco/sv-mcp"
+Issues = "https://github.com/seovendorco/sv-mcp/issues"
+Changelog = "https://github.com/seovendorco/sv-mcp/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.4",
+  "pytest-asyncio>=0.23",
+]
+
+[project.scripts]
+sv-mcp = "sv_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sv_mcp"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+asyncio_mode = "auto"