# Google Documents MCP

Servidor [Model Context Protocol](https://modelcontextprotocol.io/) para Google Docs.

**Beta cerrada:** el OAuth de Google está en modo *Testing*. Solo pueden autenticarse los usuarios añadidos manualmente como *test users* por el maintainer.

```bash
npx @0pvalencia/google-documents-mcp login
```

## Características

- Un solo login en el navegador — sin crear proyectos en Google Cloud.
- Sesión persistente por usuario en el directorio estándar del sistema.
- Cuatro herramientas MCP para Google Docs.
- Comando `doctor` con diagnóstico claro.
- Compatible con Cursor, VS Code y Claude Desktop (stdio).

### Herramientas disponibles

| Herramienta | Parámetros | Resultado |
| --- | --- | --- |
| `list_documents` | — | Los 20 documentos más recientes (`id`, `name`, `modifiedTime`) |
| `read_document` | `documentId` | Contenido del documento como texto plano |
| `create_document` | `title` | `id` y URL del documento creado |
| `append_text` | `documentId`, `text` | `OK` |

## Instalación y primer uso

1. Autentica:

```bash
npx @0pvalencia/google-documents-mcp login
```

2. Autoriza Google en el navegador (debes estar en la lista de test users).

3. Conecta el MCP en tu cliente:

   - [Cursor](./docs/clients/cursor.md)
   - [VS Code](./docs/clients/vscode.md)
   - [Claude Desktop](./docs/clients/claude-desktop.md)
   - [Claude Code](./docs/clients/claude-code.md)
   - [Índice de clientes](./docs/clients/README.md)

Solo necesitas autenticarte una vez. Comprueba el estado:

```bash
npx @0pvalencia/google-documents-mcp doctor
```

## Beta cerrada / test users

Actualmente Google OAuth está en modo testing. **Solo usuarios agregados manualmente como test users pueden autenticarse.**

Si el login falla:

1. Pide al maintainer que te añada como test user.
2. Vuelve a ejecutar `login`.

## Comandos CLI

```text
google-documents-mcp                 Inicia el servidor MCP (stdio)
google-documents-mcp login           Inicia sesión con Google
google-documents-mcp logout          Cierra la sesión local
google-documents-mcp doctor          Verifica la sesión y el acceso a las APIs
google-documents-mcp version         Muestra la versión
google-documents-mcp help            Lista los comandos
```

### Doctor

Comprueba: sesión, refresh token, usuario autenticado, Docs API, Drive API y permisos.

## Uso con clientes MCP

**[docs/clients/](./docs/clients/README.md)**

Cursor:

```json
{
  "mcpServers": {
    "google-documents": {
      "command": "npx",
      "args": ["-y", "@0pvalencia/google-documents-mcp"]
    }
  }
}
```

Ejecuta `login` una vez y reinicia los servidores MCP.

## Dónde se guarda la sesión

| Sistema | Ubicación |
| --- | --- |
| Linux | `~/.config/google-documents-mcp/` |
| macOS | `~/Library/Application Support/google-documents-mcp/` |
| Windows | `%APPDATA%\google-documents-mcp\` |

```bash
npx @0pvalencia/google-documents-mcp logout
```

## Arquitectura

```text
src/
├── auth/                 # OAuth, PKCE, sesión
├── cli/                  # login, logout, doctor, help
├── config/               # storage y rutas del SO
├── server/
│   ├── mcp.ts            # tools + services
│   └── stdio.ts          # transporte local
├── transports/
│   └── stdio.ts
├── services/docs/
├── tools/docs/
├── schemas/
├── types/
└── utils/
```

## Desarrollo (maintainers)

```bash
npm install
cp .env.example .env
npm run dev login
npm run check
npm test
```

## Roadmap

### Versión 1 (beta)

- [x] Listar / leer / crear documentos y añadir texto
- [x] Login OAuth propio con PKCE
- [x] Beta cerrada con test users

### Versión 2

- [ ] Buscar / actualizar / compartir / exportar
- [ ] Migración a OAuth público verificado

### Versión 3

- [ ] Google Drive, Sheets, Gmail, Calendar, Slides, Forms

## Contribuir

1. Fork + rama descriptiva.
2. Tipado estricto, sin `any`.
3. Nuevas herramientas solo vía `services/` + `tools/`.
4. `npm run check` y `npm test` antes del PR.

## Licencia

[MIT](./LICENSE)