npm package: @justmpm/task-request
Description: MCP App - Task Request Builder com UI interativa para criar tasks estruturadas
Author: Koda AI Studio
Latest version: 1.0.2

# @justmpm/task-request

MCP App com UI interativa para criar tasks estruturadas. Agora o pacote suporta dois modos: `stdio` para Codex local e `http` para hosts MCP por URL.

## O que é

Este é um **MCP App** - uma extensão do Model Context Protocol que inclui uma interface web interativa renderizada dentro de clientes como Claude Desktop.

## Funcionalidades

- **Formulário Visual** para criar tasks estruturadas
- **Tipos de Task**: Implementar, Corrigir, Analisar, Refatorar, Testar, Documentar
- **Prioridades**: Urgente, Normal, Baixa (com emojis visuais)
- **Campos Estruturados**:
  - Título e descrição
  - Contexto adicional (arquivos, prints, URLs)
  - Restrições (o que NÃO fazer)
  - Arquivos relacionados
  - Critérios de aceite
- **Validação em tempo real**
- **Geração automática de prompt estruturado**

## Modos de uso

### 1. `stdio` para Codex

Use quando quiser que o Codex suba o MCP automaticamente como processo local.

Comando instalado:

```bash
task-request-mcp
```

### 2. `http` para hosts por URL

Use quando quiser conectar via endpoint HTTP em hosts como `basic-host` ou connectors remotos.

Comando instalado:

```bash
task-request-mcp-http
```

## Como funciona

Esse pacote tem 3 partes:

1. `create_task`
Abre a UI dentro do host MCP.

2. `mcp-app.html` + React
Renderiza o formulario premium dentro do chat.

3. `submit_task`
Recebe os dados enviados pela UI e devolve o resultado estruturado para a conversa.

## Instalação local

```bash
# Clone ou navegue até o diretório
cd mcps-ai/task-request

# Instale dependências
npm install

# Gere UI + servidor
npm run build

# Rode o endpoint HTTP do MCP
npm run start
```

## Desenvolvimento

```bash
# Modo MCP real: recompila a UI para dist e observa alteracoes
npm run dev

# Preview visual da UI no navegador, separado do host MCP
npm run dev:ui
```

## Publicar e instalar globalmente

```bash
# Publicar no npm
npm publish --access public

# Instalar globalmente no seu PC
npm install -g @justmpm/task-request

# Rodar no modo stdio (ideal para Codex)
task-request-mcp

# Rodar no modo HTTP
task-request-mcp-http
```

## Testar no host

### Opção 1: basic-host

```bash
git clone https://github.com/modelcontextprotocol/ext-apps.git
cd ext-apps/examples/basic-host
npm install

# Aponte para o endpoint local do MCP
SERVERS='["http://localhost:3001/mcp"]' npm start

# Abra http://localhost:8080
```

### Opção 2: Claude via tunnel

```bash
npx cloudflared tunnel --url http://localhost:3001

# Adicione a URL gerada como Custom Connector no Claude
```

## Uso

1. Rode o modo HTTP:
   `task-request-mcp-http`

2. Cadastre o endpoint MCP no host:
   `http://localhost:3001/mcp`

3. No host, peça algo como:
   ```
   "Crie uma task para adicionar login com Google"
   ```

4. O host chama a tool `create_task` e o formulario aparece dentro do chat.

5. Preencha e clique em `Enviar task`.

6. A tool `submit_task` devolve a resposta estruturada automaticamente para a conversa.

## Uso no Codex

Depois de instalar globalmente, configure em `C:\Users\tetu_\.codex\config.toml`:

```toml
[mcp_servers.task_request]
command = "task-request-mcp"
enabled = true
```

Depois reabra o Codex. Nesse modo, ele sobe o MCP localmente sem precisar manter `localhost:3001` aberto manualmente.

## Configuração opcional

```bash
# Porta do servidor
PORT=3001

# Origins permitidas para o endpoint MCP
MCP_ALLOWED_ORIGINS=http://localhost:8080,http://localhost:3000
```

## Exemplo de Prompt Gerado

```markdown
## 📋 TASK: Adicionar botão de logout no header

**Tipo:** Implementar
**Prioridade:** 🟡 Normal

---

### 🎯 O que preciso

Adicionar um botão de logout no canto superior direito do header. O botão deve:
- Ter ícone de saída
- Confirmar antes de deslogar
- Chamar a função signOut() do AuthService

### 📎 Contexto Adicional

Arquivo: src/components/Header.tsx
Já existe o hook useAuth() com signOut()

### 📁 Arquivos Relacionados

- `src/components/Header.tsx`
- `src/hooks/useAuth.ts`

### ⛔ Restrições

**O que NÃO fazer:**

- Não quebrar testes existentes
- Manter padrão MUI V7

### ✅ Critérios de Aceite

1. Botão aparece no header quando logado
2. Confirmação aparece antes de deslogar
3. Usuário é redirecionado para /login após logout

---

> Task criada via Task Request Builder MCP App
```

## Stack

- **Server**: Express + MCP SDK + StreamableHTTPServerTransport
- **UI**: React 19 + MUI V7 + Vite
- **SDK**: @modelcontextprotocol/ext-apps

## Fluxo ideal

Se o seu objetivo e usar isso como builder de pedido:

1. No Codex, use `task-request-mcp` via `command`
2. Em hosts por URL, use `task-request-mcp-http`
3. Quando eu precisar estruturar uma task, eu chamo `create_task`
4. Voce preenche o formulario e eu recebo o resultado ja pronto na conversa

## Estrutura

```
task-request/
├── src/
│   ├── server.ts          # Servidor MCP com HTTP transport
│   └── ui/
│       ├── main.tsx       # Entry point React
│       ├── App.tsx        # Componente principal
│       └── types.ts       # Tipos TypeScript
├── mcp-app.html           # HTML entry point
├── vite.config.ts         # Configuração Vite
├── tsconfig.json          # TypeScript config
└── package.json
```

## Licença

MIT © Koda AI Studio