Setup uv and ci (lint, publish)

.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-groups
+
+      - name: Ruff lint
+        run: uv run ruff check --output-format=github server.py
+
+      - name: Pyrefly type check
+        run: uv run pyrefly check
+
+      - name: Build package
+        run: uv build

.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

.python-version

@@ -0,0 +1 @@
+3.11

README.md

@@ -170,8 +170,27 @@ Cada ferramenta de cadastro aceita um parâmetro `env`:
 
 ## Instalação
 
+O projeto usa [uv](https://docs.astral.sh/uv/). Instale-o com:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Uso via `uvx` (recomendado)
+
+Não é necessário clonar o repositório. O `uvx` baixa e executa o servidor em um ambiente isolado:
+
 ```bash
-pip install -r requirements.txt
+uvx databasis-mcp
+```
+
+### Desenvolvimento a partir do repositório
+
+```bash
+git clone https://github.com/basedosdados/mcp.git
+cd mcp
+uv sync          # cria o .venv e instala as dependências
+uv run server.py # executa o servidor
 ```
 
 ---
@@ -180,12 +199,12 @@ pip install -r requirements.txt
 
 As credenciais são lidas automaticamente de `~/.basedosdados/credentials.json` — não é necessário passá-las como variáveis de ambiente.
 
-Substitua `/caminho/para/python` e `/caminho/para/mcp/server.py` pelos caminhos corretos na sua máquina.
+Todos os exemplos abaixo usam `uvx`, que resolve e executa o servidor automaticamente.
 
 ### Claude Code (CLI)
 
 ```bash
-claude mcp add databasis -- /caminho/para/python /caminho/para/mcp/server.py
+claude mcp add databasis -- uvx databasis-mcp
 ```
 
 Ou adicione manualmente ao `~/.claude/settings.json`:
@@ -195,8 +214,8 @@ Ou adicione manualmente ao `~/.claude/settings.json`:
   "mcpServers": {
     "databasis": {
       "type": "stdio",
-      "command": "/caminho/para/python",
-      "args": ["/caminho/para/mcp/server.py"]
+      "command": "uvx",
+      "args": ["databasis-mcp"]
     }
   }
 }
@@ -215,8 +234,8 @@ Adicione ao `claude_desktop_config.json`:
 {
   "mcpServers": {
     "databasis": {
-      "command": "/caminho/para/python",
-      "args": ["/caminho/para/mcp/server.py"]
+      "command": "uvx",
+      "args": ["databasis-mcp"]
     }
   }
 }
@@ -231,8 +250,8 @@ Adicione ao `.vscode/mcp.json` no seu workspace (ou nas configurações globais
   "servers": {
     "databasis": {
       "type": "stdio",
-      "command": "/caminho/para/python",
-      "args": ["/caminho/para/mcp/server.py"]
+      "command": "uvx",
+      "args": ["databasis-mcp"]
     }
   }
 }
@@ -246,11 +265,14 @@ Qualquer cliente compatível com MCP via stdio pode usar o mesmo padrão:
 {
   "mcpServers": {
     "databasis": {
-      "command": "/caminho/para/python",
-      "args": ["/caminho/para/mcp/server.py"]
+      "command": "uvx",
+      "args": ["databasis-mcp"]
     }
   }
 }
 ```
 
 Consulte a documentação do seu cliente para o local exato do arquivo de configuração.
+
+> **Rodando a partir de um clone local?** Substitua `"command": "uvx", "args": ["databasis-mcp"]`
+> por `"command": "uv", "args": ["run", "--directory", "/caminho/para/mcp", "server.py"]`.

pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "databasis-mcp"
+version = "0.1.0"
+description = "MCP server exposing the Base dos Dados (basedosdados.org) API — metadata search, BigQuery queries, and metadata registration — as tools for AI agents."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Ricardo Dahis", email = "rdahis@basedosdados.org" }]
+keywords = ["mcp", "basedosdados", "bigquery", "llm", "data"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "fastmcp>=3.4,<4",
+    "requests>=2.31",
+    "google-cloud-bigquery>=3.0",
+    "types-requests>=2.33.0.20260712",
+]
+
+[project.urls]
+Homepage = "https://basedosdados.org"
+Repository = "https://github.com/basedosdados/mcp"
+
+[project.scripts]
+databasis-mcp = "server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["server.py"]
+
+[dependency-groups]
+dev = [
+    "pyrefly>=1.1.1",
+    "ruff>=0.16.0",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 80
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+]
+
+ignore = [
+  # line-to-long
+  "E501"
+]
+
+[tool.pyrefly]
+project-includes = ["server.py"]
+python-version = "3.11"

server.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.basedosdados/mcp",
+  "description": "Exposes the Base dos Dados (basedosdados.org) API as tools for AI agents: metadata search, BigQuery queries, and metadata registration.",
+  "repository": {
+    "url": "https://github.com/basedosdados/mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "databasis-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "description": "Target backend environment: local, dev, staging, or prod. Defaults to dev.",
+          "isRequired": false,
+          "format": "string",
+          "name": "ENV"
+        },
+        {
+          "description": "GCP project charged for BigQuery queries. Falls back to ~/.basedosdados/credentials.json (gcp_project).",
+          "isRequired": false,
+          "format": "string",
+          "name": "GCP_PROJECT_ID"
+        },
+        {
+          "description": "Base dos Dados backend token (bdtoken_...). Required only for write tools; falls back to ~/.basedosdados/credentials.json.",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": true,
+          "name": "BACKEND_TOKEN"
+        }
+      ]
+    }
+  ]
+}