convez.ai
MCP ServerMarketing & VendasIntermediário
Lab2A

Metalworks — Pesquisa de Demanda Fundamentada em Reddit

Lab2A/metalworks

Valide ideias de startup lendo demanda real em conversas do Reddit

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que analisa conversas reais do Reddit para validar ideias de produtos, fornecendo posicionamento, análise competitiva, plano de construção e copy de lançamento — tudo rastreável até comentários autênticos. Funciona como biblioteca Python, CLI e servidor MCP, com múltiplos provedores LLM suportados e camadas de busca, embeddings e armazenamento intercambiáveis.

Instalação

$npx convez-ai Lab2A/metalworks

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
7
Forks
1
Acompanhando
0
Saúde
87%
Último commit
há 4 meses
Versão
—
Issues abertas
14
Contribuidores
2

Casos de uso

  • Validar se existe demanda real para uma ideia de produto antes de construir
  • Pesquisar posicionamento e estratégia competitiva baseada em discussões autênticas
  • Gerar planos de lançamento e copy de marketing fundamentados em feedback real

Veredito

Ferramenta sólida para fundadores validarem teses de produto com rigor — cada afirmação é rastreável até um comentário real, eliminando achismo. Pre-release, mas com API estável na fachada principal; requer cuidado com a política de uso do Reddit (apenas engajamento autêntico e divulgado).

README

A tradução para o português deste README ainda está na fila.

metalworks

Go from a startup idea to launch, grounded in real demand.

Give metalworks one sentence about what you want to build. It reads real Reddit conversations to tell you whether people actually want it, then turns that into the things you need to launch: your positioning, the competitors to beat, a marketing site, a build plan for your coding agent, and launch copy. Every claim links back to a real comment you can click — nothing is invented.

A Python library (also a CLI, an MCP server, and a Claude Code plugin). MIT licensed and built to be embedded — every layer (LLM, search, embeddings, storage, data source) is a swappable protocol.

Status: pre-release (0.0.1). APIs are unstable below 1.0. The stable surface is the Metalworks facade, the metalworks.contract Pydantic models, and the MCP tool contracts. Everything else may change in any 0.x release. Some surfaces below are marked planned for 0.1 where they are not wired yet; this README is honest about what runs today.

Read the USAGE_POLICY before you use the Reddit side. Short version: authentic, disclosed engagement only. No fake personas, no vote manipulation, no coordinated inauthentic behavior.

Quickstart

Install metalworks with a provider SDK and set one key — any provider works:

pip install "metalworks[openai,research]"   # or [google,research], [anthropic,research]
export OPENAI_API_KEY=...                    # or ANTHROPIC_API_KEY / GOOGLE_API_KEY / OPENROUTER_API_KEY

Embeddings need no separate key: with a Google or OpenAI key metalworks uses theirs, otherwise it falls back to a small local model (fastembed, bundled with [research], downloaded once). So a single chat key — Anthropic, OpenRouter, anything — gets you a full run. metalworks models warm pre-downloads the local model.

Prefer Vertex AI over an API key? Set GOOGLE_GENAI_USE_VERTEXAI=true plus VERTEX_PROJECT_ID and VERTEX_LOCATION and the Google adapters authenticate via Application Default Credentials. See docs/configuration.md.

from metalworks import Metalworks

mw = Metalworks()             # provider inferred; or Metalworks(model="anthropic/claude-opus-4-6")
research = mw.research("Is there demand for a focus supplement aimed at developers?",
                       subreddits=["Nootropics", "Supplements"])
report = research.demand

Every quote in report.ranked_clusters is the exact text of a real Reddit comment, and every web finding carries its real source URL — never model prose. Anything metalworks can't back with a real quote, it drops. See why you can trust the output.

The Metalworks facade is the easy path over run_research / run_discovery and the protocols — drop down to those whenever you want more control. Submissions come from the Hugging Face open-index/arctic Parquet mirror; comments from the live Arctic Shift API. Set HF_TOKEN for windows beyond a few months. To read the submission corpus from a Supabase Storage bucket instead (no HF runtime dependency), install metalworks[supabase] and set ARCTIC_SHIFT_SOURCE=mirror, or bring your own corpus to skip Arctic Shift.

Extras

Core stays lean (pydantic, httpx, typer, rich). Everything that pulls a provider SDK or a heavy dependency lives behind an extra, so you install only what matches the keys you have. Adapters lazy-import their SDK and raise MissingExtraError with the exact pip install command when it is absent.

pip install "metalworks[google]"
pip install "metalworks[research,reddit]"
pip install "metalworks[all]"
ExtraPulls inFor
anthropicanthropicClaude ChatModel adapter
openaiopenaiOpenAI ChatModel + embedding adapters
googlegoogle-genaiGemini ChatModel (native grounding) + embeddings
litellmlitellmOptional long-tail provider routing
redditredditwarp, cryptographyReddit search, OAuth, posting, token encryption
arcticduckdbRead Arctic Shift Parquet shards (submissions corpus)
researcharctic + rank-bm25The full demand-report pipeline
supabasearctic + supabaseArcticMirrorReader — Arctic corpus from a Supabase Storage bucket (ARCTIC_SHIFT_SOURCE=mirror)
exaexa-pyExa SearchProvider adapter
tavilytavily-pythonTavily SearchProvider adapter
mcpmcp[cli]MCP server surface
alleverything aboveKitchen sink
devpytest, ruff, pyright, respxContributors

A bare import metalworks pulls in no provider modules; CI asserts this.

Architecture

metalworks owns small, versioned protocols and ships thin adapters over official provider SDKs. It does not route every provider through LiteLLM by default. The protocols are the seam your code and the pipeline speak through:

  • ChatModel — complete_text / complete_structured, model bound at adapter construction. GroundedChatModel adds model-native web grounding with full provenance (chunks plus character-offset supports).
  • SearchProvider — external web search (Exa, Tavily).
  • EmbeddingProvider — embeddings with a hard index-identity guard.
  • The typed repos (CorpusRepo, BriefRepo, RunRepo, AccountRepo, OpportunityRepo, InboxRepo) are the storage protocol. MemoryStores and SqliteStores ship in core; hosted backends (Postgres/PostgREST) are a custom store you implement downstream — see docs/custom-store.md.

See docs/protocols.md for signatures.

Two verticals sit on top of those protocols:

  • Research (metalworks.research) — turns an idea into a clustered DemandReport of real, permalinked Reddit quotes. Entry point: run_research(deps, brief=...). Seven functions build on a finished report, each linking its output back to that report's real quotes: positioning (build_positioning_brief), competitors (run_competitor_map), surface + UX (decide_surface / build_ux_skeleton), marketing site (build_marketing_site), launch assets (build_launch_assets / plan_channels), a content/SEO plan (content_plan_from_report), and a build plan + scaffold (build_spec_from_report / scaffold).
  • Reddit (metalworks.reddit) — OAuth, search, subreddit intel, inbox, posting, in-library rate limiting, and a deterministic compliance gate (heuristic_check) that runs offline on reply and post text.

Four form factors share that contract:

  1. Library — from metalworks import Metalworks, or the functions and protocols underneath.
  2. CLI — metalworks research|reddit|arctic|discovery run, the report commands (metalworks research position|competitor-map|surface|site|launch|content-plan, metalworks build init), metalworks doctor, metalworks mcp serve.
  3. MCP server — zero-key data tools plus key-gated pipeline tools, over stdio or SSE.
  4. Claude Code plugin — /demand-report and friends (/plugin marketplace add Lab2A/metalworks).

Testing your own adapters and backends

The conformance suites metalworks holds itself to ship as a public module:

from metalworks.testing import FakeChatModel, FakeEmbedding, check_all_repos

def test_my_backend():
    check_all_repos(MyBackend())   # includes the >1000-row pagination case

See docs/custom-chatmodel.md and docs/custom-store.md.

Docs

Full docs: metalworks.lab2a.ai

Project

Ver o original no GitHub

Bom para

Relacionados