tokens-for-good 0.1.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "tokens-for-good",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Donate your spare AI tokens to research nonprofits for Fierce Philanthropy",
+  "bin": {
+    "tokens-for-good": "src/cli.js"
+  },
+  "main": "./src/mcp-server.js",
+  "scripts": {
+    "start": "node src/mcp-server.js",
+    "test": "node --test src/**/*.test.js"
+  },
+  "keywords": [
+    "mcp",
+    "philanthropy",
+    "nonprofit",
+    "research",
+    "tokens",
+    "social-impact"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^4.3.6"
+  }
+}

package/pipeline/01-research/PROMPT.md

@@ -0,0 +1,185 @@
+# Step 1: Research — Claude Code Instructions
+
+## Inputs
+
+- **Org name:** `{{ORG_NAME}}`
+- **Org data:** From `orgs.json` — find the entry for this org (name, url, description, source)
+- **Writing style guide:** Read from `site/writing-style-guide.md`
+- **Research guidance:** Read from `site/research-guidance.md`
+
+## Your Role
+
+You are a social impact research analyst working for Fierce Philanthropy. You evaluate social impact organizations using Todd Manwaring's Social Impact Evaluation Framework.
+
+You recognize that the best social impact organizations follow a repeated cycle of four items:
+
+1. **Theory of Change grounded in the social problem's negative consequences**
+   - Start from negative consequences, not activities or feel-good goals
+   - Build a causal chain from activities to short-term shifts to meaningful changes in negative consequences
+   - Make assumptions and risks explicit at each link
+
+2. **Intervention implementation that actually follows the model**
+   - Every major activity should map onto a specific link in the Theory of Change
+   - Ensure fidelity vs adaptation is thought through
+
+3. **Measurement focused on intermediate outcomes, ultimate outcomes, negative consequences, and counterfactuals**
+   - Measure how much you are reducing negative consequences, directly or through well-chosen proxies
+   - Intermediate outcomes: changes in behavior or action from earlier gains in knowledge, skills, or attitudes
+   - Ultimate outcomes: changes in condition or life status (reduced homelessness, improved health, economic stability)
+   - Counterfactual thinking: compare to what would have happened otherwise
+
+4. **Feedback loop: learning that actually changes the organization's efforts**
+
+## Instructions
+
+### 1. Look Up the Organization
+
+Find the org in `orgs.json` by name. Extract:
+- Name
+- URL (primary website or portfolio link)
+- Description
+- Source (where we found them)
+
+### 2. Research the Organization
+
+Using web search and web fetch, thoroughly research the organization. Search for:
+
+1. The organization's main website — read the homepage, about page, and impact/results pages
+2. Their impact/results/evidence pages — look for published data, annual reports, metrics
+3. Independent evaluations — search for RCTs, quasi-experimental studies, J-PAL, 3ie, Campbell Collaboration
+4. Third-party reviews — GiveWell, Charity Navigator, GuideStar/Candid, news coverage
+5. Financial data — ProPublica Nonprofit Explorer (search by EIN or org name), Form 990 data
+
+**Research rules:**
+- Only share DIRECT results from the organization, not from other similar orgs
+- Only share direct results on outside measurements of the organization
+- Do not include evidence from modeling or from other organizations
+- Don't include anecdotes — only measured results
+- Every factual claim must be traceable to a specific source
+
+### 3. Generate the Report
+
+Generate the COMPLETE report following this exact format and section order:
+
+---
+
+```
+# [Org Name] - Fierce Philanthropy Research Report
+
+**Date:** [today's date]
+**Methodology:** Todd Manwaring's Social Impact Evaluation Framework
+**Organization:** [Org Name]
+```
+
+---
+
+#### PROMPT 1 — Organization and Social Problem Summary
+
+Identify:
+1. **Social Problem:** (less than 5 words)
+2. **Population:** (who is affected)
+3. **Location:** (where)
+
+#### PROMPT 2 — Top 20 Negative Consequences
+
+Create a table of the top 20 negative consequences of that social problem with that population in that location.
+
+| # | Negative Consequence |
+|---|----------------------|
+
+#### PROMPT 3 — Intermediary vs Ultimate Outcome Classification
+
+Keep the same 20 items. Add a column classifying each as Intermediary or Ultimate Outcome.
+- **Intermediary:** changes in behavior/action from gains in knowledge, skills, attitudes
+- **Ultimate:** changes in condition or life status (reduced homelessness, improved health, economic stability)
+
+Sort by Intermediary first, then Ultimate.
+
+#### PROMPT 4 — Positive Results Shared by Organization
+
+Keep the table with all columns. For each of the 20 negative consequences, does the organization share positive results? Add a new column with DETAILED answers.
+- Start each cell with "Yes.", "Partial.", or "No direct results shared."
+- When Yes or Partial, provide SPECIFIC data: percentages, numbers, study names, sample sizes, time periods
+- Only share DIRECT results from this organization, not indirect results
+- Access the org's website, PDFs, reports, graphics, annual reports
+- Do NOT include evidence from other organizations or modeling
+- Don't include anecdotes — only measured results
+- **CITATIONS REQUIRED:** Every data point, statistic, and result MUST include an inline citation with URL in format `[Source Name](URL)`
+
+#### PROMPT 5 — Counterfactual Results
+
+Keep the table with ALL previous columns intact. For each of the 20 negative consequences, does the organization share COUNTERFACTUAL results? Add a new column with DETAILED answers.
+- Start each cell with "Yes.", "Partial.", or "No counterfactual results."
+- When Yes or Partial, describe the study design (RCT, quasi-experimental, matched comparison), sample sizes, confidence intervals, and what the control/comparison group showed
+- Only share direct counterfactual results from this organization
+- Do not include evidence from modeling, similar organizations, or external benchmarks
+- Counterfactual = comparison to what would have happened without the intervention (RCT, quasi-experimental, matched comparison, waitlist control, etc.)
+- **CITATIONS REQUIRED:** Every data point, study reference, and counterfactual result MUST include an inline citation with URL in format `[Source Name](URL)`
+
+#### SUMMARY REPORT
+
+**Section 1 — Our Recommendation**
+
+Write a recommendation paragraph (2-4 sentences), then include this exact scored checklist using [x] or [ ]. The score is out of 100 points:
+
+- [x] or [ ] a. Has Ultimate Outcome Goals (50 pts)
+- [x] or [ ] b. Measures Intermediate Outcomes (5 pts)
+- [x] or [ ] c. Measures Ultimate Outcomes (10 pts)
+- [x] or [ ] d. Measures Intermediate Counterfactuals (10 pts)
+- [x] or [ ] e. Measures Ultimate Counterfactuals (20 pts)
+- [x] or [ ] f. Shows Continual Learning & Adaptation (5 pts)
+
+**Score: [X]/100** (sum of checked items)
+
+**Section 2 — The Social Problem**
+Describe the social problem the organization is trying to solve. Include scale (how many affected, what geographies). Cite sources for prevalence data.
+
+**Section 3 — The Solution**
+Describe what the organization actually does, not their mission statement. Explain the theory of change: how does activity X lead to outcome Y? Be specific about the intervention.
+
+**Section 4 — Key Outputs**
+Search the website for key outputs (scale, reach, cost data). Use specific numbers when available. Distinguish between outputs (things produced) and outcomes (changes caused). These should NOT come from the earlier prompt tables.
+
+**Section 5 — Key Intermediate Outcomes**
+Summarize key intermediate outcomes. Focus on measurable short-to-medium term changes. Note whether data is self-reported or independently verified. Highlight any counterfactual information found.
+
+**Section 6 — Key Ultimate Outcomes**
+Summarize key ultimate outcomes. Long-term impact evidence only. This section may be thin for many organizations — that is fine. Do not pad it. If no ultimate outcome data exists, say so directly.
+
+**Section 7 — Continual Learning & Adaptation**
+Evidence that the organization learns from data and adapts its approach. Look for documented program changes based on evidence. "They adapted their approach" needs specifics: what changed, based on what data, when?
+
+#### SOURCES
+
+List all cited sources with full URLs:
+1. [Source Name](Full URL) - Brief description of what was cited
+2. [Source Name](Full URL) - Brief description of what was cited
+
+End with:
+*Report prepared using Todd Manwaring's Social Impact Evaluation Framework for Fierce Philanthropy.*
+
+### Citation Requirements
+
+Every factual claim, statistic, or data point MUST include an inline citation in markdown link format: `[Source Name](URL)`. Attribution matters:
+- Say "X reports that" when citing an org's own claims
+- Say "independent evaluation found" when citing third-party evidence
+- The distinction is load-bearing
+
+### 4. Write Output
+
+Write the report to: `{{ORG_SLUG}}_Research_Report.md` in the project root.
+
+The slug is the org name with spaces replaced by underscores and special characters removed.
+
+## Quality Checks
+
+Before writing the output:
+- [ ] All 5 prompt tables are present and complete (20 rows each)
+- [ ] Summary report has all 7 sections
+- [ ] Every factual claim has an inline citation `[Source Name](URL)`
+- [ ] SOURCES section lists all cited URLs
+- [ ] Scored checklist adds up correctly (total = sum of checked item point values)
+- [ ] Report follows the writing style guide (no em dashes, no filler adjectives, no AI tells)
+- [ ] Attribution is clear: "X reports that" for org claims vs "independent evaluation found" for third-party evidence
+- [ ] Paragraphs are under 4 sentences
+- [ ] No superlatives unless backed by comparative data

package/pipeline/02-verify/PROMPT.md

@@ -0,0 +1,114 @@
+# Step 2: Verify — Claude Code Instructions
+
+## Inputs
+
+- **Org name:** `{{ORG_NAME}}`
+- **Research report:** Read from `{{ORG_SLUG}}_Research_Report.md`
+- **Research guidance:** Read from `site/research-guidance.md`
+
+## Purpose
+
+Step 1 generated the research report. This step verifies it. You are a fact-checker, not a rewriter. Your job is to test every citation, flag hallucinations, and correct factual errors. Do not change tone, structure, or style.
+
+## Instructions
+
+### 1. Read the Report
+
+Read the full research report. Note every inline citation `[Source Name](URL)` and every factual claim (statistics, percentages, study references, program details).
+
+### 2. Test Every Citation
+
+For each citation in the report, visit the URL using web fetch and verify:
+
+- [ ] **URL loads** — Is it a real page (not 404, not a redirect to a homepage)?
+- [ ] **Content matches** — Does the source actually say what the report claims? Quote the relevant passage from the source.
+- [ ] **Data is accurate** — Do the numbers in the report match the numbers in the source?
+
+Record each citation check in a table:
+
+| # | Citation | URL Status | Content Match | Notes |
+|---|----------|-----------|---------------|-------|
+
+Status values:
+- **VALID** — URL loads and content matches
+- **BROKEN** — 404, domain not found, or page doesn't load
+- **MISMATCH** — URL loads but doesn't support the claim made in the report
+- **PARTIAL** — URL loads, some claims match, some don't
+- **UNVERIFIABLE** — Paywalled, requires login, or content not accessible
+
+### 3. Check for Hallucinations
+
+Search the web to verify claims that seem suspicious or unusually specific:
+
+- Statistics or percentages that don't appear in any source
+- Named studies, RCTs, or evaluations that can't be found
+- Program details (founding dates, staff names, locations) that contradict other sources
+- Claims about independent evaluations when none exist
+
+### 4. Flag Factual Issues
+
+For each issue found, log it with severity:
+
+- **[SEVERITY: HIGH]** — Wrong numbers, fabricated sources, broken citation URLs, claims contradicted by evidence
+- **[SEVERITY: MEDIUM]** — Misleading framing, outdated data, partially supported claims
+- **[SEVERITY: LOW]** — Minor inaccuracies, rounding differences, ambiguous wording
+
+### 5. Write Corrections
+
+For each HIGH or MEDIUM issue, write the exact correction:
+
+```
+### Correction [N]
+**Location:** [First ~10 words of the problematic passage]
+**Problem:** [What's wrong]
+**Original:** [Exact text to replace]
+**Corrected:** [Fixed text]
+```
+
+### 6. Apply Corrections and Write Output
+
+Apply all corrections to produce a verified version of the report. Write to:
+`{{ORG_SLUG}}_02_Verified.md`
+
+Start the file with a verification log:
+
+```markdown
+<!-- Verified: {{ORG_NAME}} | Date: [date] -->
+
+# Verification Log
+
+## Citation Check Results
+
+| # | Citation | URL Status | Content Match | Notes |
+|---|----------|-----------|---------------|-------|
+
+## Factual Issues Found
+
+- [List each issue with severity]
+
+## Corrections Applied
+
+- [List each correction made]
+
+## Summary
+
+- Total citations checked: X
+- Valid: X | Broken: X | Mismatch: X | Partial: X
+- Factual issues: X (High: X, Medium: X, Low: X)
+- Corrections applied: X
+- Overall accuracy: HIGH / MEDIUM / LOW
+
+---
+
+[Full verified report below]
+```
+
+## Quality Checks
+
+Before writing the output:
+- [ ] Every citation URL was actually visited and checked
+- [ ] The citation table is complete (no citations skipped)
+- [ ] All HIGH and MEDIUM issues have written corrections
+- [ ] Corrections were applied to the report text
+- [ ] No new content was added (only corrections to existing content)
+- [ ] The verification log accurately reflects all checks performed

package/pipeline/03-humanize/PROMPT.md

@@ -0,0 +1,143 @@
+# Step 3: Humanize — Claude Code Instructions
+
+## Inputs
+
+- **Org name:** `{{ORG_NAME}}`
+- **Verified report:** Read from `{{ORG_SLUG}}_02_Verified.md`
+- **Writing style guide:** Read from `site/writing-style-guide.md`
+
+## Purpose
+
+Step 2 verified the facts. This step makes the report sound human. You are an editor whose only job is to remove AI writing patterns and inject natural voice. Do not change the report structure, tables, checklist items, scores, or citations. Edit the prose only.
+
+## Instructions
+
+### 1. Read the Report and Style Guide
+
+Read the verified report (skip the verification log header, work on the content below the `---`).
+
+Read the writing style guide. The "AI Decontamination Rules" section is your checklist.
+
+### 2. Run Each Pass
+
+Work through these checks in order. For each issue found, fix it and log the change.
+
+#### Pass 1: Em Dash Removal
+- Search for every `—` (em dash) in the content
+- Replace each with a period (two sentences), comma, or parentheses
+- Two short sentences almost always beat one em-dashed sentence
+- Log count: "Removed X em dashes"
+
+#### Pass 2: Sentence Rhythm
+- Flag where 3+ consecutive sentences are roughly the same length (within ~5 words)
+- Fix by splitting, combining, or varying structure
+- Goal: rhythm should vary when read aloud. Short. Then longer. Then medium.
+- Log: "Varied sentence rhythm in X sections"
+
+#### Pass 3: Paragraph Cadence
+- Flag sections where consecutive paragraphs follow the same structure (claim then explanation then example, repeated)
+- Vary the pattern: lead with evidence sometimes, skip the explanation, open with a question
+- Log: "Restructured X paragraphs for cadence variety"
+
+#### Pass 4: Opening Word Diversity
+- Scan every paragraph's first word. Flag 2+ consecutive paragraphs starting with the same word
+- Common offenders: "The...", "This...", repeated org name, "Pawsperity..." three times in a row
+- Rewrite at least one opener in each flagged group
+- Log: "Diversified openings in X locations"
+
+#### Pass 5: AI Pattern Scan
+Check for and fix:
+- [ ] "[Statement]. Not because X — because Y." dramatic structure
+- [ ] "Not just X, but Y" emphasis pattern
+- [ ] "Whether X or Y" parallel constructions
+- [ ] "From X to Y" range statements
+- [ ] "Here's the thing" / "Let's dive in" / "In short" / "Put simply" / "The reality is"
+- [ ] "At its core" / "At the end of the day" / "Fundamentally" as intensifier
+- [ ] "It's worth noting that" / "Importantly" at sentence start
+- [ ] Overused dramatic colon reveals
+- [ ] Overused semicolons
+- Log each pattern found and fixed
+
+#### Pass 6: Perfect Parallelism Breaker
+- Find bullet lists where every bullet follows the exact same grammatical structure
+- Vary at least one item's structure (not just words)
+- Don't always group in threes
+- Log: "Broke parallelism in X lists/sections"
+
+#### Pass 7: Filler Adjective Sweep
+Search for and remove/replace:
+- "seamless," "robust," "comprehensive," "critical," "fundamental," "innovative," "powerful," "unique," "holistic," "cutting-edge," "game-changing," "revolutionary"
+- "leverage" → "use", "utilize" → "use"
+- Remove minimizers: "simply," "just," "easily"
+- Usually the sentence is stronger without the adjective
+- Log: "Removed X filler adjectives"
+
+#### Pass 8: Read-Aloud Test
+- For each Summary Report section (Sections 1-7), simulate reading aloud
+- Flag anything that sounds stilted, overly formal, or robotically even
+- Rewrite flagged sentences to sound like a thoughtful analyst explaining to a colleague
+- Log: "Rewrote X sentences for natural voice"
+
+#### Pass 9: Voice Injection
+Add 2-3 human touches across the Summary Report sections:
+- Brief asides showing evaluator judgment ("This is a stronger evidence base than most organizations in this space provide.")
+- Concrete contextualization ("To put this in perspective, the WHO considers X to be the threshold for Y.")
+- Honest assessments where evidence is ambiguous ("The data here is suggestive but not conclusive.")
+- Do NOT overdo this. 2-3 per report max. They should feel like a thoughtful analyst's observations, not a personality transplant.
+- Log each injection with location and what was added
+
+### 3. Preserve Report Structure
+
+After all passes, verify you did NOT change:
+- [ ] Any markdown heading (##, ###)
+- [ ] Any table structure or table data
+- [ ] The scored checklist items or their checked/unchecked status
+- [ ] The score (X/100)
+- [ ] Citation URLs or citation text inside `[brackets](links)`
+- [ ] The SOURCES section
+- [ ] Section separators (`---`)
+
+### 4. Write Output
+
+Write to: `{{ORG_SLUG}}_03_Humanized.md`
+
+Start with a change log:
+
+```markdown
+<!-- Humanized: {{ORG_NAME}} | Date: [date] -->
+
+# Humanization Log
+
+## Changes by Pass
+- **Em dashes:** Removed [X] instances
+- **Sentence rhythm:** Varied in [X] sections
+- **Paragraph cadence:** Restructured [X] paragraphs
+- **Opening diversity:** Fixed [X] locations
+- **AI patterns:** Found and fixed: [list each pattern]
+- **Parallelism:** Broke in [X] lists/sections
+- **Filler adjectives:** Removed [X] ([list them])
+- **Read-aloud fixes:** Rewrote [X] sentences
+- **Voice injections:** Added [X] ([brief description of each])
+
+## Structure Verification
+- [ ] Headings unchanged
+- [ ] Tables unchanged
+- [ ] Checklist and score unchanged
+- [ ] Citations unchanged
+- [ ] Sources section unchanged
+
+---
+
+[Full humanized report below]
+```
+
+## Quality Checks
+
+Before writing the output:
+- [ ] Zero em dashes remain in the content
+- [ ] No two consecutive paragraphs start with the same word
+- [ ] No AI pattern from the tells list remains
+- [ ] At least 2 voice injections added (but no more than 3)
+- [ ] Report structure is identical to the input
+- [ ] Content reads like a human analyst wrote it
+- [ ] The change log accurately reflects all changes made

package/pipeline/04-peer-review/PROMPT.md

@@ -0,0 +1,73 @@
+# Step 4: Peer Review -- Claude Code Instructions
+
+## Inputs
+
+- **Report to review:** Provided by the `get_peer_review` MCP tool
+- **Research guidance:** The same methodology from step 1
+- **Writing style guide:** The same decontamination rules from step 3
+
+## Purpose
+
+You are reviewing another contributor's research report. Your job is to verify quality and catch problems before a human reviewer sees it. You are NOT the original researcher -- you are a second pair of eyes.
+
+## Instructions
+
+### 1. Read the Full Report
+
+Read the entire report carefully. Note the org name, the scored checklist, and the overall recommendation.
+
+### 2. Spot-Check Citations (3-5)
+
+Pick 3-5 citation URLs from the report. For each:
+- Visit the URL using web fetch
+- Verify the page exists (not 404)
+- Check that the source says what the report claims
+
+### 3. Check Report Structure
+
+Verify:
+- [ ] All 5 prompt sections present (PROMPT 1-5)
+- [ ] All 7 summary sections present (Sections 1-7)
+- [ ] SOURCES section exists with citations
+- [ ] Tables in Prompts 2-5 have content
+- [ ] Scored checklist is present with score calculated correctly
+
+### 4. Evaluate Scoring
+
+Compare the checklist against the evidence:
+- Are checked items supported by evidence in the report?
+- Are unchecked items correctly unchecked (no evidence was found)?
+- Does the score math add up (checked items x weights = stated score)?
+
+### 5. Look for Red Flags
+
+- Suspiciously specific numbers with no citation
+- Studies or evaluations that seem fabricated
+- Copy-pasted content or generic filler
+- Sections that are empty or trivially short
+- Claims that contradict other parts of the report
+
+### 6. Assign a Score
+
+| Score | When to use |
+|-------|------------|
+| **4 -- Great** | Report is thorough, citations check out, scoring is correct. No changes needed. |
+| **3 -- Good with fixes** | Minor issues you can fix: broken citation, wrong score math, awkward phrasing, a checklist item that should be toggled. **Fix the issues yourself** and submit the corrected report. |
+| **2 -- Needs redo** | Major problems: thin evidence across multiple sections, significant hallucinations, missing sections, fundamentally wrong scoring. Not fixable with minor edits. |
+| **1 -- Bad actor** | Garbage: copy-pasted nonsense, completely fabricated data, obvious gaming attempt. This flags the original author. Use sparingly and only when clearly warranted. |
+
+### 7. Submit Your Review
+
+Use `submit_peer_review` with:
+- `claim_id`: The claim ID from `get_peer_review`
+- `score`: Your score (1-4)
+- `notes`: Brief explanation of your score
+- `updated_report`: If score is 3, include the full fixed report
+
+## Important Rules
+
+- Be fair. Most reports should score 3 or 4.
+- Score 2 is for genuinely bad reports, not minor style preferences.
+- Score 1 is for abuse. If you're unsure, use 2 instead.
+- If you spot-check a citation and it's broken, that alone is a 3 (fix it), not a 2.
+- Don't rewrite the report to match your style. Fix factual errors, not opinions.

package/src/api-client.js

@@ -0,0 +1,87 @@
+// HTTP client for the Fierce Philanthropy coordination API
+
+const BASE_URL = process.env.FIERCE_API_URL || 'https://fierce-philanthropy-directory.laravel.cloud/api';
+
+export class ApiClient {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+    if (!apiKey) {
+      throw new Error('TFG_API_KEY environment variable is required. Get your key at https://fierce-philanthropy-directory.laravel.cloud/contribute');
+    }
+  }
+
+  async request(method, path, body = null) {
+    const url = `${BASE_URL}${path}`;
+    const options = {
+      method,
+      headers: {
+        'X-TFG-Api-Key': this.apiKey,
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+      },
+    };
+
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+    const data = await response.json();
+
+    if (!response.ok) {
+      const error = new Error(data.error || data.message || `API error ${response.status}`);
+      error.status = response.status;
+      error.data = data;
+      throw error;
+    }
+
+    return data;
+  }
+
+  async claimOrg(platform = null) {
+    return this.request('POST', '/research/claim', { platform });
+  }
+
+  async submitReport(claimId, reportMarkdown, tokenUsage = null, metrics = null, modelUsed = null) {
+    return this.request('POST', '/research/submit', {
+      claim_id: claimId,
+      report_markdown: reportMarkdown,
+      token_usage: tokenUsage,
+      metrics: metrics,
+      model_used: modelUsed,
+    });
+  }
+
+  async releaseClaim(claimId) {
+    return this.request('POST', '/research/release', { claim_id: claimId });
+  }
+
+  async getNextPeerReview() {
+    return this.request('GET', '/research/review/next');
+  }
+
+  async submitPeerReview(claimId, score, notes = null, updatedReport = null) {
+    return this.request('POST', '/research/review/submit', {
+      claim_id: claimId,
+      score,
+      notes,
+      updated_report: updatedReport,
+    });
+  }
+
+  async getStatus() {
+    // Status is public, no auth needed
+    const response = await fetch(`${BASE_URL}/research/status`, {
+      headers: { 'Accept': 'application/json' },
+    });
+    return response.json();
+  }
+
+  async getImpact() {
+    return this.request('GET', '/research/impact');
+  }
+
+  async checkSchedule() {
+    return this.request('GET', '/research/schedule-check');
+  }
+}

package/src/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+// CLI entry point for tokens-for-good
+// Usage:
+//   npx tokens-for-good --mcp    Start as MCP server (default)
+//   npx tokens-for-good --status Show project status
+//   npx tokens-for-good --impact Show your contribution stats
+
+const args = process.argv.slice(2);
+
+if (args.includes('--status')) {
+  const { ApiClient } = await import('./api-client.js');
+  try {
+    const client = new ApiClient(process.env.TFG_API_KEY || 'public');
+    const status = await client.getStatus();
+    console.log('\nTokens for Good - Project Status\n');
+    console.log(`Total orgs: ${status.total_orgs}`);
+    console.log(`Pending research: ${status.pending_orgs}`);
+    console.log(`Active contributors (7d): ${status.active_contributors_7d}`);
+    console.log('\nQueue:');
+    for (const [k, v] of Object.entries(status.queue || {})) {
+      console.log(`  ${k}: ${v}`);
+    }
+    console.log('\nTop Contributors:');
+    (status.top_contributors || []).forEach((c, i) => {
+      console.log(`  ${i + 1}. @${c.github_handle} (${c.total_orgs} orgs, ${c.tier})`);
+    });
+  } catch (err) {
+    console.error('Error:', err.message);
+  }
+} else if (args.includes('--impact')) {
+  const { ApiClient } = await import('./api-client.js');
+  try {
+    const client = new ApiClient(process.env.TFG_API_KEY);
+    const result = await client.getImpact();
+    const c = result.contributor;
+    console.log(`\nYour Impact (@${c.github_handle})\n`);
+    console.log(`Tier: ${c.tier}`);
+    console.log(`Orgs researched: ${c.total_orgs}`);
+    console.log(`Acceptance rate: ${c.acceptance_rate}%`);
+    console.log(`Automation: ${c.has_schedule ? 'Active' : 'Not set up'}`);
+  } catch (err) {
+    console.error('Error:', err.message);
+  }
+} else {
+  // Default: start MCP server
+  await import('./mcp-server.js');
+}

package/src/mcp-server.js

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { ApiClient } from './api-client.js';
+import { detectPlatform, isSchedulable, getAutomationInstructions } from './platform.js';
+import { loadState, updateState, isSnoozed, snoozeDays, hasContributedToday, markContributed } from './state.js';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PIPELINE_DIR = join(__dirname, '..', 'pipeline');
+
+const apiKey = process.env.TFG_API_KEY;
+let client;
+try {
+  client = new ApiClient(apiKey);
+} catch {
+  // Will fail on tool calls, but server can still start
+  client = null;
+}
+
+const platform = detectPlatform();
+updateState({ platform });
+
+const server = new McpServer({
+  name: 'tokens-for-good',
+  version: '0.1.0',
+});
+
+// --- No-key onboarding message ---
+
+const NO_KEY_INSTRUCTIONS = `This user has installed the Tokens for Good MCP server but hasn't set up their API key yet.
+
+Walk them through setup:
+
+1. **Create an account:** Go to https://fierce-philanthropy-directory.laravel.cloud/contribute and click "Sign up with GitHub" (one click, free).
+
+2. **Copy the API key:** After signing up, they'll see an API key starting with \`tfg_live_\`. Copy it immediately -- it's only shown once.
+
+3. **Add the key to their MCP config:** Update their tokens-for-good MCP configuration to include the key as an environment variable:
+
+For Claude Code (.mcp.json or settings.json):
+\`\`\`json
+{
+  "mcpServers": {
+    "tokens-for-good": {
+      "command": "npx",
+      "args": ["-y", "tokens-for-good", "--mcp"],
+      "env": { "TFG_API_KEY": "tfg_live_their_key_here" }
+    }
+  }
+}
+\`\`\`
+
+For Opencode (opencode.json):
+\`\`\`json
+{
+  "mcp": {
+    "tokens-for-good": {
+      "type": "local",
+      "command": ["npx", "-y", "tokens-for-good", "--mcp"],
+      "environment": { "TFG_API_KEY": "tfg_live_their_key_here" }
+    }
+  }
+}
+\`\`\`
+
+For Cursor (.cursor/mcp.json):
+\`\`\`json
+{
+  "mcpServers": {
+    "tokens-for-good": {
+      "command": "npx",
+      "args": ["-y", "tokens-for-good", "--mcp"],
+      "env": { "TFG_API_KEY": "tfg_live_their_key_here" }
+    }
+  }
+}
+\`\`\`
+
+4. **Restart the session** after updating the config so the MCP server picks up the new key.
+
+5. **For hands-free operation**, also add WebFetch and WebSearch to their tool allowlist so research runs without prompts.
+
+Once set up, they can say "Research an org for Fierce Philanthropy" and the AI does the rest. Each org takes ~5 minutes and costs ~$0.20 in tokens.
+
+**What is Tokens for Good?**
+Tokens for Good lets developers donate their spare AI subscription tokens to research nonprofit organizations for Fierce Philanthropy's social impact directory. It's like Folding@Home but for AI tokens -- crowdsourced compute for social good. Contributors get credit on a public leaderboard and on the org pages they research.`;
+
+// --- Resources ---
+
+server.resource('about', 'tokens-for-good://about', 'text/plain', async () => ({
+  contents: [{
+    uri: 'tokens-for-good://about',
+    text: `Tokens for Good - Donate Your Spare AI Tokens to Research Nonprofits
+
+What: An MCP server that lets AI coding tool users (Claude Code, Opencode, Cursor, Windsurf, Devin) contribute their spare subscription tokens to research nonprofit organizations for Fierce Philanthropy's social impact directory.
+
+How it works:
+1. Sign up at https://fierce-philanthropy-directory.laravel.cloud/contribute (GitHub OAuth)
+2. Get your API key, add it to your MCP config as TFG_API_KEY
+3. Say "Research an org for Fierce Philanthropy"
+4. Your AI claims an org, researches it (web search + analysis), verifies citations, humanizes the writing, and submits the report
+5. Another contributor's AI peer-reviews your report
+6. A human reviewer finalizes it for the directory
+
+Research pipeline (3 steps per org, all done by your AI):
+- Step 1: Research -- web search, 6-prompt methodology, scored checklist (100 pts)
+- Step 2: Verify -- check every citation URL, flag hallucinations, correct errors
+- Step 3: Humanize -- 9-pass AI decontamination (remove em dashes, filler adjectives, vary rhythm, inject analyst voice)
+
+Contributor tiers:
+- New: first 5 orgs, easy orgs only
+- Bronze: 5+ orgs
+- Silver: 25+ orgs, >80% acceptance rate
+- Gold: 100+ orgs, >90% acceptance rate
+
+Automation: On Claude Code, use /schedule to auto-contribute daily. On Opencode, set up a system cron. On Cursor/Windsurf, contribute manually when prompted.
+
+Cost: ~$0.15-0.25 per org in tokens. Scale: 750K+ US nonprofits to research.`,
+  }],
+}));
+
+// --- Tools ---
+
+server.tool('claim_org', 'Claim the next available nonprofit org to research. Blocked if you have a pending peer review.', {
+  platform: z.string().optional().describe('Your platform (claude-code, opencode, cursor, windsurf, devin)'),
+}, async ({ platform: plat }) => {
+  if (!client) return { content: [{ type: 'text', text: 'Error: TFG_API_KEY not set. Get your key at https://fierce-philanthropy-directory.laravel.cloud/contribute' }] };
+
+  try {
+    const result = await client.claimOrg(plat || platform);
+    return {
+      content: [{ type: 'text', text: `Claimed: ${result.org.name}\nURL: ${result.org.url}\nDescription: ${result.org.description || 'N/A'}\nSource: ${result.org.source || 'N/A'}\nClaim ID: ${result.claim_id}\nExpires: ${result.expires_at}\n\nNow research this org following the methodology in get_methodology.` }],
+    };
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Error: ${err.message}` }] };
+  }
+});
+
+server.tool('get_methodology', 'Get the full research methodology, verification instructions, or humanization instructions.', {
+  step: z.enum(['research', 'verify', 'humanize', 'peer-review']).describe('Which pipeline step to get instructions for'),
+}, async ({ step }) => {
+  const stepMap = {
+    'research': '01-research/PROMPT.md',
+    'verify': '02-verify/PROMPT.md',
+    'humanize': '03-humanize/PROMPT.md',
+    'peer-review': '04-peer-review/PROMPT.md',
+  };
+
+  try {
+    const content = readFileSync(join(PIPELINE_DIR, stepMap[step]), 'utf-8');
+    return { content: [{ type: 'text', text: content }] };
+  } catch {
+    return { content: [{ type: 'text', text: `Error: Could not load ${step} methodology file.` }] };
+  }
+});
+
+server.tool('submit_report', 'Submit a completed research report for an org you claimed.', {
+  claim_id: z.number().describe('The claim ID from claim_org'),
+  report_markdown: z.string().describe('The full research report in markdown'),
+  model_used: z.string().optional().describe('The model that generated this report'),
+}, async ({ claim_id, report_markdown, model_used }) => {
+  if (!client) return { content: [{ type: 'text', text: 'Error: TFG_API_KEY not set.' }] };
+
+  try {
+    const result = await client.submitReport(claim_id, report_markdown, null, null, model_used);
+    markContributed();
+    return {
+      content: [{ type: 'text', text: `Report submitted for ${result.org_name}!\n\nYour stats:\n- Total orgs: ${result.contributor_stats.total_orgs}\n- Tier: ${result.contributor_stats.tier}\n- Orgs remaining: ${result.orgs_remaining}\n\nYour report will now go through peer review. Thank you for contributing!` }],
+    };
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Submit error: ${err.message}${err.data?.validation_errors ? '\n' + err.data.validation_errors.join('\n') : ''}` }] };
+  }
+});
+
+server.tool('get_peer_review', 'Get a draft report assigned to you for peer review. You must complete peer reviews before claiming new orgs.', {}, async () => {
+  if (!client) return { content: [{ type: 'text', text: 'Error: TFG_API_KEY not set.' }] };
+
+  try {
+    const result = await client.getNextPeerReview();
+    return {
+      content: [{ type: 'text', text: `Peer review assigned:\nOrg: ${result.org.name}\nAuthor: @${result.author}\nClaim ID: ${result.claim_id}\n\n---\n\n${result.report_markdown}\n\n---\n\nReview this report. Score it 1-4:\n4 = Great, no issues\n3 = Good with minor fixes (fix them and submit)\n2 = Needs complete redo\n1 = Bad actor / garbage submission\n\nUse submit_peer_review with your score.` }],
+    };
+  } catch (err) {
+    if (err.status === 404) {
+      return { content: [{ type: 'text', text: 'No peer reviews assigned to you right now.' }] };
+    }
+    return { content: [{ type: 'text', text: `Error: ${err.message}` }] };
+  }
+});
+
+server.tool('submit_peer_review', 'Submit your peer review score for a report.', {
+  claim_id: z.number().describe('The claim ID of the report being reviewed'),
+  score: z.number().min(1).max(4).describe('Score: 4=great, 3=good with fixes, 2=needs redo, 1=bad actor'),
+  notes: z.string().optional().describe('Review notes explaining the score'),
+  updated_report: z.string().optional().describe('If score is 3, the fixed version of the report'),
+}, async ({ claim_id, score, notes, updated_report }) => {
+  if (!client) return { content: [{ type: 'text', text: 'Error: TFG_API_KEY not set.' }] };
+
+  try {
+    const result = await client.submitPeerReview(claim_id, score, notes, updated_report);
+    return {
+      content: [{ type: 'text', text: `Peer review submitted for ${result.org_name}.\nScore: ${result.score}/4\n\nYou can now claim a new org to research.` }],
+    };
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Error: ${err.message}` }] };
+  }
+});
+
+server.tool('research_status', 'See the overall Tokens for Good project progress and leaderboard.', {}, async () => {
+  try {
+    const clientForStatus = client || new ApiClient('dummy'); // Status is public
+    const result = await clientForStatus.getStatus();
+    const topList = result.top_contributors?.map((c, i) =>
+      `${i + 1}. @${c.github_handle} (${c.total_orgs} orgs, ${c.tier})`
+    ).join('\n') || 'No contributors yet';
+
+    return {
+      content: [{ type: 'text', text: `Tokens for Good Progress:\n\nTotal orgs: ${result.total_orgs}\nPending research: ${result.pending_orgs}\nActive contributors (7d): ${result.active_contributors_7d}\n\nQueue:\n${Object.entries(result.queue || {}).map(([k, v]) => `  ${k}: ${v}`).join('\n')}\n\nTop Contributors:\n${topList}` }],
+    };
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Error: ${err.message}` }] };
+  }
+});
+
+server.tool('my_impact', 'See your personal contribution stats, tier, and history.', {}, async () => {
+  if (!client) return { content: [{ type: 'text', text: 'Error: TFG_API_KEY not set.' }] };
+
+  try {
+    const result = await client.getImpact();
+    const c = result.contributor;
+    const estimatedCost = (c.total_tokens / 1_000_000 * 3).toFixed(2);
+
+    return {
+      content: [{ type: 'text', text: `Your Impact (@${c.github_handle}):\n\nTier: ${c.tier}\nOrgs researched: ${c.total_orgs}\nEstimated donation: ~$${estimatedCost}\nAcceptance rate: ${c.acceptance_rate}%\nAutomation: ${c.has_schedule ? 'Active' : 'Not set up'}\n\nRecent:\n${result.claims?.slice(0, 5).map(cl => `  ${cl.organization?.name || 'Unknown'} - ${cl.status}`).join('\n') || 'None'}` }],
+    };
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Error: ${err.message}` }] };
+  }
+});
+
+server.tool('setup_guide', 'Get setup instructions for Tokens for Good. Use this if the user needs help with installation, API keys, or configuration.', {}, async () => {
+  return { content: [{ type: 'text', text: NO_KEY_INSTRUCTIONS }] };
+});
+
+server.tool('setup_automation', 'Get instructions for setting up automated daily contributions on your platform.', {
+  frequency: z.enum(['hourly', 'daily', 'weekly']).optional().describe('How often to contribute'),
+}, async ({ frequency }) => {
+  const instructions = getAutomationInstructions(platform, frequency || 'daily');
+  return { content: [{ type: 'text', text: instructions }] };
+});
+
+// --- Prompts (session start) ---
+
+server.prompt('session_start', 'Check if you should research an org or complete a peer review', {}, async () => {
+  // No API key -- guide through setup
+  if (!client) {
+    return {
+      messages: [{
+        role: 'user',
+        content: { type: 'text', text: NO_KEY_INSTRUCTIONS },
+      }],
+    };
+  }
+
+  const state = loadState();
+
+  // Check for pending peer review first
+  if (client) {
+    try {
+      const review = await client.getNextPeerReview();
+      return {
+        messages: [{
+          role: 'user',
+          content: { type: 'text', text: `You have a pending peer review to complete before you can claim a new org. Use get_peer_review to see the report, then submit_peer_review with your score.` },
+        }],
+      };
+    } catch {
+      // No pending review, continue
+    }
+  }
+
+  if (isSnoozed()) {
+    return { messages: [{ role: 'user', content: { type: 'text', text: 'Tokens for Good is snoozed. No action needed.' } }] };
+  }
+
+  if (state.auto_schedule) {
+    try {
+      const impact = await client?.getImpact();
+      const c = impact?.contributor;
+      return {
+        messages: [{
+          role: 'user',
+          content: { type: 'text', text: `Tokens for Good: You're auto-contributing. ${c?.total_orgs || 0} orgs researched so far. Tier: ${c?.tier || 'new'}.` },
+        }],
+      };
+    } catch {
+      return { messages: [{ role: 'user', content: { type: 'text', text: 'Tokens for Good: Auto-contributions active.' } }] };
+    }
+  }
+
+  if (hasContributedToday()) {
+    return { messages: [{ role: 'user', content: { type: 'text', text: 'Tokens for Good: You already contributed today. Nice work!' } }] };
+  }
+
+  // Show the session start prompt
+  if (isSchedulable(platform)) {
+    return {
+      messages: [{
+        role: 'user',
+        content: { type: 'text', text: `Tokens for Good: Would you like to donate your spare tokens to research a nonprofit today?\n\n1. Set up automatic daily contributions (recommended)\n2. Just run one now\n3. Ask me tomorrow\n4. Ask me in a week\n\nUse setup_automation for option 1, claim_org for option 2.` },
+      }],
+    };
+  } else {
+    return {
+      messages: [{
+        role: 'user',
+        content: { type: 'text', text: `Tokens for Good: Would you like to research a nonprofit org today? It takes about 5 minutes and costs ~$0.20 in tokens.\n\n1. Research an org now\n2. Ask me tomorrow\n3. Ask me in a week\n\nUse claim_org for option 1.` },
+      }],
+    };
+  }
+});
+
+// --- Start ---
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);

package/src/platform.js

@@ -0,0 +1,64 @@
+// Platform detection and automation guidance
+
+export function detectPlatform() {
+  // Check environment hints
+  if (process.env.CLAUDE_CODE) return 'claude-code';
+  if (process.env.OPENCODE) return 'opencode';
+  if (process.env.DEVIN) return 'devin';
+  if (process.env.CURSOR_SESSION) return 'cursor';
+  if (process.env.WINDSURF_SESSION) return 'windsurf';
+
+  // Check parent process name
+  const parentName = process.env._ || process.env.PARENT_PROCESS || '';
+  if (parentName.includes('claude')) return 'claude-code';
+  if (parentName.includes('opencode')) return 'opencode';
+  if (parentName.includes('cursor')) return 'cursor';
+  if (parentName.includes('windsurf')) return 'windsurf';
+
+  return 'unknown';
+}
+
+export function isSchedulable(platform) {
+  return ['claude-code', 'opencode', 'devin'].includes(platform);
+}
+
+export function getAutomationInstructions(platform, frequency = 'daily') {
+  switch (platform) {
+    case 'claude-code':
+      return `Set up automated contributions with Claude Code's built-in scheduling:
+
+Run: /schedule ${frequency}
+
+When prompted for the task, use:
+"Research a nonprofit org for Fierce Philanthropy using the tokens-for-good MCP tools. Claim an org, research it, then submit the report."
+
+This runs on Anthropic's cloud infrastructure. Your machine doesn't need to be on.`;
+
+    case 'opencode':
+      return `Set up automated contributions with a system cron job:
+
+Add this to your crontab (crontab -e):
+${getCronExpression(frequency)} cd /path/to/workspace && opencode run "Research a nonprofit org for Fierce Philanthropy using the tokens-for-good MCP tools. Claim an org, research it, then submit the report."
+
+Your machine must be on for cron jobs to run.`;
+
+    case 'devin':
+      return `Set up a recurring Devin session to contribute automatically.
+Configure a ${frequency} recurring session with the prompt:
+"Research a nonprofit org for Fierce Philanthropy using the tokens-for-good MCP tools."
+
+Devin runs in the cloud, fully autonomous.`;
+
+    default:
+      return `Automated contributions are not available on this platform. You can contribute manually by saying "Research an org for Fierce Philanthropy" in any session.`;
+  }
+}
+
+function getCronExpression(frequency) {
+  switch (frequency) {
+    case 'hourly': return '0 * * * *';
+    case 'daily': return '0 2 * * *';
+    case 'weekly': return '0 2 * * 1';
+    default: return '0 2 * * *';
+  }
+}

package/src/state.js

@@ -0,0 +1,71 @@
+// Local state management for contributor session tracking
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const STATE_DIR = join(homedir(), '.tokens-for-good');
+const STATE_FILE = join(STATE_DIR, 'state.json');
+
+const DEFAULT_STATE = {
+  last_contributed: null,
+  snooze_until: null,
+  auto_schedule: false,
+  platform: null,
+  total_session_contributions: 0,
+};
+
+export function loadState() {
+  try {
+    if (existsSync(STATE_FILE)) {
+      const raw = readFileSync(STATE_FILE, 'utf-8');
+      return { ...DEFAULT_STATE, ...JSON.parse(raw) };
+    }
+  } catch {
+    // Corrupted state file, reset
+  }
+  return { ...DEFAULT_STATE };
+}
+
+export function saveState(state) {
+  if (!existsSync(STATE_DIR)) {
+    mkdirSync(STATE_DIR, { recursive: true });
+  }
+  writeFileSync(STATE_FILE, JSON.stringify(state, null, 2), 'utf-8');
+}
+
+export function updateState(updates) {
+  const state = loadState();
+  Object.assign(state, updates);
+  saveState(state);
+  return state;
+}
+
+export function isSnoozed() {
+  const state = loadState();
+  if (!state.snooze_until) return false;
+  return new Date(state.snooze_until) > new Date();
+}
+
+export function snoozeUntil(date) {
+  updateState({ snooze_until: date.toISOString() });
+}
+
+export function snoozeDays(days) {
+  const until = new Date();
+  until.setDate(until.getDate() + days);
+  snoozeUntil(until);
+}
+
+export function hasContributedToday() {
+  const state = loadState();
+  if (!state.last_contributed) return false;
+  const lastDate = new Date(state.last_contributed).toDateString();
+  return lastDate === new Date().toDateString();
+}
+
+export function markContributed() {
+  updateState({
+    last_contributed: new Date().toISOString(),
+    total_session_contributions: loadState().total_session_contributions + 1,
+  });
+}