# DevCard — The Agent-Native GitHub Presence Engine

> MCP Server + Agent Skills + GitHub Action
> "Hey Claude, audit my GitHub and make it agent-ready."

---

## What We're Building

**DevCard** is an MCP server + agent skill that lets any AI coding agent (Claude Code, Cursor, Copilot, Windsurf, etc.) audit, generate, fix, and maintain a developer's GitHub presence — optimized for both human visibility and AI agent readability.

The developer never runs a CLI. They never visit a website. They just tell their agent:

```
"Audit my GitHub profile and fix what's broken"
"Generate my DevCard"
"Make my repos agent-ready"
"Compare me with @sindresorhus"
```

The agent does everything.

---

## Why MCP + Skills Is the Right Play

| Distribution Channel | Reach | Effort |
|---|---|---|
| CLI tool on PyPI | Developers who find it, install it, remember to run it | High friction |
| Web app | Requires hosting, auth, maintenance | Ongoing cost |
| **MCP Server** | **Every Claude Code, Cursor, Copilot, Windsurf user** | **One install command** |
| **Agent Skill** | **Claude Code's 35M+ users** | **Drop a .md file** |

The MCP ecosystem is exploding right now. GitHub's official MCP server already has massive adoption. Claude Code skills are a proven distribution channel — the awesome-claude-code-toolkit repo has catalogued 135+ agents, 35+ skills, 176+ plugins. Getting listed in these directories = instant visibility.

**One install command:**
```bash
claude mcp add devcard -- npx @devcard/mcp-server
```

That's it. The developer now has DevCard available in every Claude Code session.

---

## Architecture

```
┌───────────────────────────────────────────────────────┐
│                    AGENT HOSTS                        │
│  Claude Code · Cursor · Copilot · Windsurf · VS Code │
│                                                       │
│  Developer says: "audit my github"                    │
│  Agent calls DevCard MCP tools automatically          │
└──────────────────────┬────────────────────────────────┘
                       │ MCP Protocol (stdio / HTTP)
                       │
┌──────────────────────▼────────────────────────────────┐
│              DEVCARD MCP SERVER                        │
│                                                       │
│  Tools exposed to agents:                             │
│  ┌─────────────────────────────────────────────────┐  │
│  │ audit_profile    → Scan & score GitHub presence  │  │
│  │ generate_devcard → Create devcard.json + SVG     │  │
│  │ analyze_repo     → Deep-dive single repo         │  │
│  │ fix_profile      → Auto-fix profile issues       │  │
│  │ fix_repo         → Auto-fix repo issues          │  │
│  │ agent_ready      → Add agent-readiness files     │  │
│  │ compare_devs     → Compare two developers        │  │
│  │ render_card      → Generate visual SVG/PNG card  │  │
│  └─────────────────────────────────────────────────┘  │
│                                                       │
│  Resources exposed:                                   │
│  ┌─────────────────────────────────────────────────┐  │
│  │ devcard://schema/v1          → JSON Schema       │  │
│  │ devcard://{username}/card    → Generated card     │  │
│  │ devcard://{username}/audit   → Audit results      │  │
│  └─────────────────────────────────────────────────┘  │
│                                                       │
│  Prompts (pre-built workflows):                       │
│  ┌─────────────────────────────────────────────────┐  │
│  │ full_audit       → Complete profile audit flow   │  │
│  │ quick_card       → Just generate a DevCard       │  │
│  │ make_agent_ready → Full agent-readiness workflow  │  │
│  │ profile_compare  → Compare two developers        │  │
│  └─────────────────────────────────────────────────┘  │
│                                                       │
│  ┌─────────────────────────────────────────────────┐  │
│  │              ENGINE (Python core)                │  │
│  │                                                  │  │
│  │  github/     → Async API client + cache          │  │
│  │  extractors/ → Identity, languages, stack, etc.  │  │
│  │  analyzers/  → Dev type, quality, scoring        │  │
│  │  renderers/  → SVG card, markdown, JSON          │  │
│  │  fixers/     → Auto-fix generators               │  │
│  │  mappings/   → Dependency + topic heuristics     │  │
│  └─────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────┘
```

---

## The MCP Tools (What Agents Can Call)

### 1. `audit_profile`
**The entry point. This is what people will use most.**

```
Input:  { username: "chiragxarora", token?: "ghp_xxx" }
Output: {
  human_visibility_score: 72,
  agent_readiness_score: 18,
  issues: [
    { severity: "high",   type: "missing_bio",           message: "No bio set on profile" },
    { severity: "high",   type: "missing_profile_readme", message: "No profile README (username/username repo)" },
    { severity: "medium", type: "missing_descriptions",   repos: ["repo1", "repo2"], count: 8 },
    { severity: "medium", type: "missing_topics",         repos: ["repo3"], count: 12 },
    { severity: "medium", type: "stale_readmes",          repos: ["old-project"], count: 3 },
    { severity: "low",    type: "missing_licenses",       repos: ["util-lib"], count: 5 },
    { severity: "high",   type: "no_devcard_json",        message: "No devcard.json in profile repo" },
    { severity: "medium", type: "no_agents_md",           repos: ["main-project"], count: 4 },
    { severity: "low",    type: "no_llms_txt",            repos: ["docs-heavy-project"], count: 2 }
  ],
  summary: {
    total_repos: 42,
    repos_with_descriptions: 34,
    repos_with_topics: 30,
    repos_with_license: 37,
    repos_with_readme: 38,
    repos_with_agents_md: 0,
    repos_with_devcard: 0,
    repos_with_llms_txt: 0
  },
  recommendations: [
    "Add a profile README with your DevCard SVG",
    "Add descriptions to 8 repos",
    "Add topics to 12 repos",
    "Generate devcard.json for agent discoverability",
    "Add AGENTS.md to your 5 most active repos"
  ]
}
```

**Scoring breakdown:**

Human Visibility Score (0-100):
- Bio completeness (10 pts)
- Profile README exists + quality (15 pts)
- Repo descriptions coverage (15 pts)
- Topic coverage (10 pts)
- README quality across repos (15 pts)
- License coverage (5 pts)
- Pinned repos set up (5 pts)
- Activity recency (10 pts)
- Social links present (5 pts)
- Contribution graph activity (10 pts)

Agent Readiness Score (0-100):
- devcard.json exists in profile repo (20 pts)
- AGENTS.md in active repos (20 pts)
- llms.txt in documentation-heavy repos (10 pts)
- Structured README with parseable sections (15 pts)
- Proper dependency files (10 pts)
- Topics/metadata completeness (10 pts)
- Machine-readable project classification (10 pts)
- Clean commit messages (5 pts)

### 2. `generate_devcard`
**Creates the structured DevCard.**

```
Input:  { username: "torvalds", include_svg: true }
Output: {
  devcard: { ... full devcard.json ... },
  svg: "<svg>...</svg>",
  markdown_summary: "## Linus Torvalds\n..."
}
```

### 3. `analyze_repo`
**Deep-dive into a single repository.**

```
Input:  { owner: "chiragxarora", repo: "agent-auth" }
Output: {
  classification: "library",
  status: "active",
  primary_language: "Python",
  stack: ["FastAPI", "Pydantic", "Redis"],
  quality: { has_tests: true, has_ci: true, has_docs: true, score: 85 },
  issues: [
    { type: "missing_topics", suggestion: ["oauth", "ai-agents", "sdk", "python"] },
    { type: "no_agents_md", suggestion: "Auto-generate AGENTS.md for this repo" },
    { type: "readme_could_improve", details: "Missing: installation section, API examples" }
  ],
  suggested_description: "OAuth-as-a-Service SDK for AI agents — handles token exchange, storage, refresh, and scoping",
  suggested_topics: ["oauth", "ai-agents", "sdk", "python", "authentication", "mcp"]
}
```

### 4. `fix_profile`
**Generates fixes for profile-level issues.**

```
Input:  {
  username: "chiragxarora",
  token: "ghp_xxx",
  fixes: ["profile_readme", "devcard_json", "missing_descriptions"],
  dry_run: true  // Preview changes without applying
}
Output: {
  changes: [
    {
      type: "create_file",
      repo: "chiragxarora/chiragxarora",
      path: "README.md",
      content: "# Hi, I'm Chirag 👋\n...\n![DevCard](./devcard.svg)\n...",
      description: "Profile README with embedded DevCard"
    },
    {
      type: "create_file",
      repo: "chiragxarora/chiragxarora",
      path: "devcard.json",
      content: "{ ... }",
      description: "Structured agent-readable developer identity"
    },
    {
      type: "create_file",
      repo: "chiragxarora/chiragxarora",
      path: "devcard.svg",
      content: "<svg>...</svg>",
      description: "Visual DevCard for README embedding"
    },
    {
      type: "update_repo_description",
      repo: "chiragxarora/old-project",
      old: "",
      new: "A CLI tool for batch processing CSV files with custom transformations",
      description: "Auto-generated description from README analysis"
    }
  ],
  dry_run: true,
  message: "Preview of 4 changes. Run with dry_run=false to apply."
}
```

### 5. `fix_repo`
**Generates fixes for a specific repo.**

```
Input:  {
  owner: "chiragxarora",
  repo: "agent-auth",
  token: "ghp_xxx",
  fixes: ["topics", "agents_md", "llms_txt", "description"],
  dry_run: false  // Actually apply
}
Output: {
  applied: [
    { type: "update_topics", topics: ["oauth", "ai-agents", "sdk", "python"] },
    { type: "create_file", path: "AGENTS.md", content: "..." },
    { type: "create_file", path: "llms.txt", content: "..." },
    { type: "update_description", new: "OAuth-as-a-Service SDK for AI agents" }
  ],
  status: "success",
  message: "4 fixes applied to chiragxarora/agent-auth"
}
```

### 6. `agent_ready`
**The one-command "make everything agent-ready" tool.**

```
Input:  {
  username: "chiragxarora",
  token: "ghp_xxx",
  scope: "all"  // or "profile" or "top_repos"
}
Output: {
  actions: [
    "Created devcard.json in profile repo",
    "Created devcard.svg in profile repo",
    "Updated profile README with DevCard embed",
    "Added AGENTS.md to 5 active repos",
    "Added llms.txt to 2 documentation-heavy repos",
    "Added topics to 8 repos",
    "Added descriptions to 3 repos"
  ],
  before: { human_score: 72, agent_score: 18 },
  after:  { human_score: 89, agent_score: 76 },
  message: "Your GitHub presence is now agent-ready. Score improved from 18 → 76."
}
```

### 7. `compare_devs`
**Side-by-side developer comparison.**

```
Input:  { user1: "torvalds", user2: "gvanrossum" }
Output: {
  comparison: {
    user1: { name: "Linus Torvalds", type: "systems-engineer", ... },
    user2: { name: "Guido van Rossum", type: "language-designer", ... },
    overlapping_languages: ["C", "Python"],
    different_strengths: {
      user1: ["kernel development", "low-level systems"],
      user2: ["language design", "standard libraries"]
    }
  },
  markdown_comparison: "| Metric | torvalds | gvanrossum |\n..."
}
```

### 8. `render_card`
**Generate visual card in different formats/themes.**

```
Input:  { username: "chiragxarora", theme: "dark", format: "svg" }
Output: { svg: "<svg>...</svg>", embed_markdown: "![DevCard](url)" }
```

---

## The Agent Skill (Claude Code Integration)

The skill file teaches Claude Code how to orchestrate the MCP tools into workflows.

### `.claude/commands/devcard.md`

```markdown
# DevCard — GitHub Presence Engine

You have access to the DevCard MCP server. Use it to help the user
audit, improve, and maintain their GitHub presence for both human
visibility and AI agent readability.

## Available workflows:

### Full Audit (default when user says "audit my github")
1. Call `audit_profile` with the user's GitHub username
2. Display scores visually:
   - Human Visibility: XX/100
   - Agent Readiness: XX/100
3. List issues grouped by severity (high → medium → low)
4. Ask the user which issues they want to fix
5. For each fix, call the appropriate fix tool with `dry_run: true` first
6. Show the preview and ask for confirmation
7. Apply with `dry_run: false`

### Quick DevCard (when user says "generate my devcard")
1. Call `generate_devcard` with SVG enabled
2. Save devcard.json and devcard.svg to the working directory
3. Show the markdown summary
4. Offer to add it to their profile repo

### Make Agent-Ready (when user says "make my repos agent-ready")
1. Call `audit_profile` to get current agent_readiness_score
2. Show what's missing (devcard.json, AGENTS.md, llms.txt, topics)
3. Call `agent_ready` with `dry_run: true` to preview all changes
4. Show the full changeset and before/after scores
5. Ask for confirmation
6. Apply all changes

### Fix Specific Repo (when user mentions a specific repo)
1. Call `analyze_repo` for the specific repo
2. Show findings: classification, quality score, issues
3. Offer fixes: topics, description, AGENTS.md, llms.txt
4. Apply selected fixes

### Compare (when user says "compare me with @someone")
1. Call `compare_devs` with both usernames
2. Display the comparison table
3. Highlight strengths and interesting differences

## Rules:
- Always show a preview (dry_run) before making changes
- Never push to repos without explicit user confirmation
- If no GitHub token is available, ask the user to provide one
- Be honest about scores — don't sugarcoat a bad audit
- After fixes, re-run audit to show the improvement
```

### Multi-agent compatibility

The skill ships as:
- `.claude/commands/devcard.md` → Claude Code
- `.cursor/rules/devcard.mdc` → Cursor
- `AGENTS.md` section → GitHub Copilot
- `.gemini/skills/devcard/` → Gemini CLI

A single conversion script generates all formats from one source.

---

## What AGENTS.md Looks Like (Auto-Generated)

When DevCard adds `AGENTS.md` to a repo, here's what it generates:

```markdown
# AGENTS.md

## Project Overview
agent-auth is a Python library that provides OAuth-as-a-Service
for AI agents. It handles token exchange, storage, refresh, scoping,
and revocation with pre-built connectors for Google, Slack, Notion,
GitHub, and Salesforce.

## Tech Stack
- Language: Python 3.11+
- Framework: FastAPI
- Database: Redis (token storage), PostgreSQL (user data)
- Testing: pytest, pytest-asyncio
- CI: GitHub Actions

## Project Structure
- `src/agentauth/` — Core library code
  - `connectors/` — OAuth provider connectors
  - `storage/` — Token storage backends
  - `sdk/` — Public SDK interface
- `tests/` — Test suite
- `docs/` — Documentation
- `examples/` — Usage examples

## Key Patterns
- Async-first architecture (all I/O is async)
- Pydantic v2 for all data models
- Factory pattern for connector creation
- Strategy pattern for storage backends

## Development Commands
- `uv run pytest` — Run tests
- `uv run ruff check .` — Lint
- `uv run ruff format .` — Format
- `uv sync` — Install dependencies

## Contributing
- All PRs require tests
- Follow conventional commits
- Run the full test suite before submitting
```

This is generated purely from code analysis — no LLM needed:
- Tech stack from dependency files
- Structure from directory listing
- Commands from pyproject.toml / Makefile / package.json scripts
- Patterns from code analysis (async usage, import patterns)

---

## What llms.txt Looks Like (Auto-Generated)

For documentation-heavy repos:

```markdown
# agent-auth

> OAuth-as-a-Service SDK for AI agents

## Docs
- [Quick Start](docs/quickstart.md): Getting started with agent-auth in 5 minutes
- [Connectors Guide](docs/connectors.md): How to use and create OAuth connectors
- [Storage Backends](docs/storage.md): Configuring token storage (Redis, PostgreSQL, memory)
- [SDK Reference](docs/api-reference.md): Complete SDK API documentation

## Examples
- [Basic Usage](examples/basic.py): Simple token exchange flow
- [Multi-Provider](examples/multi_provider.py): Using multiple OAuth providers
- [Custom Connector](examples/custom_connector.py): Building a custom connector
```

---

## Repo Structure

```
devcard/
│
├── src/
│   ├── devcard/
│   │   ├── __init__.py
│   │   ├── server.py                      # MCP server entry point
│   │   ├── config.py
│   │   │
│   │   ├── tools/                          # MCP tool handlers
│   │   │   ├── __init__.py
│   │   │   ├── audit.py                    # audit_profile tool
│   │   │   ├── generate.py                 # generate_devcard tool
│   │   │   ├── analyze.py                  # analyze_repo tool
│   │   │   ├── fix_profile.py              # fix_profile tool
│   │   │   ├── fix_repo.py                 # fix_repo tool
│   │   │   ├── agent_ready.py              # agent_ready tool
│   │   │   ├── compare.py                  # compare_devs tool
│   │   │   └── render.py                   # render_card tool
│   │   │
│   │   ├── github/                         # GitHub API layer
│   │   │   ├── client.py                   # Async httpx client, rate limiting
│   │   │   ├── models.py                   # Pydantic models
│   │   │   └── cache.py                    # diskcache for API responses
│   │   │
│   │   ├── extractors/                     # Data extraction (no LLM)
│   │   │   ├── identity.py
│   │   │   ├── languages.py
│   │   │   ├── stack.py                    # THE dependency parser
│   │   │   ├── activity.py
│   │   │   ├── projects.py
│   │   │   ├── collaboration.py
│   │   │   ├── quality.py
│   │   │   └── expertise.py
│   │   │
│   │   ├── analyzers/                      # Signal processing
│   │   │   ├── developer_type.py
│   │   │   ├── project_classifier.py
│   │   │   ├── contribution_style.py
│   │   │   ├── scoring.py                  # Human + Agent readiness scores
│   │   │   └── issue_detector.py           # Find what's wrong
│   │   │
│   │   ├── fixers/                         # Auto-fix generators
│   │   │   ├── description_generator.py    # Generate repo descriptions
│   │   │   ├── topic_suggester.py          # Suggest topics from code
│   │   │   ├── agents_md_generator.py      # Generate AGENTS.md
│   │   │   ├── llms_txt_generator.py       # Generate llms.txt
│   │   │   ├── profile_readme_generator.py # Generate profile README
│   │   │   └── devcard_deployer.py         # Deploy devcard.json + SVG
│   │   │
│   │   ├── renderers/
│   │   │   ├── svg_card.py                 # Visual card generator
│   │   │   ├── markdown.py                 # Markdown summary
│   │   │   └── themes/
│   │   │       ├── default.py
│   │   │       ├── dark.py
│   │   │       ├── minimal.py
│   │   │       ├── neon.py
│   │   │       └── terminal.py
│   │   │
│   │   └── enrichment/                     # Optional LLM layer
│   │       ├── litellm_client.py
│   │       └── summarizer.py
│   │
│   └── devcard_cli/                        # Optional CLI (for non-MCP usage)
│       └── cli.py
│
├── mappings/
│   ├── dependencies.yaml                   # 500+ dep → category mappings
│   ├── topics_to_domains.yaml
│   ├── file_patterns.yaml
│   └── dev_type_rules.yaml
│
├── schema/
│   ├── devcard.v1.schema.json
│   └── examples/
│
├── skills/                                 # Agent skill files
│   ├── claude-code/
│   │   └── devcard.md                      # Claude Code skill
│   ├── cursor/
│   │   └── devcard.mdc                     # Cursor rules
│   ├── copilot/
│   │   └── devcard-agents.md               # Copilot agent instructions
│   └── convert.sh                          # Generate all formats from source
│
├── gallery/                                # Pre-generated famous dev cards
│   ├── torvalds.svg
│   ├── karpathy.svg
│   └── ...
│
├── action/                                 # GitHub Action
│   ├── action.yml
│   └── entrypoint.sh
│
├── tests/
│   ├── fixtures/
│   ├── test_tools/
│   ├── test_extractors/
│   ├── test_fixers/
│   └── test_renderers/
│
├── pyproject.toml
├── README.md
├── LICENSE                                 # Apache 2.0
└── AGENTS.md                               # Our own AGENTS.md (dogfooding)
```

---

## Tech Stack

| Component | Choice | Why |
|---|---|---|
| MCP Framework | `mcp` (official Python SDK) | First-class MCP support |
| Language | Python 3.11+ | Widest agent ecosystem compatibility |
| HTTP Client | `httpx` | Async, modern, connection pooling |
| Data Models | `pydantic` v2 | Schema validation, JSON Schema generation |
| Cache | `diskcache` | Zero-config local caching |
| SVG Rendering | Jinja2 templates + SVG | No heavy deps, GitHub-compatible output |
| CLI (optional) | `typer` | For non-MCP usage |
| LLM (optional) | `litellm` | Any provider, activated with flag |
| Testing | `pytest` + `pytest-asyncio` | Standard |
| Packaging | `uv` | Modern, fast |
| Publishing | PyPI + npm (via npx wrapper) | Both ecosystems |

---

## Installation Methods

### Claude Code (recommended)
```bash
# One command. Done.
claude mcp add devcard -- npx @devcard/mcp-server

# Or with Python directly
claude mcp add devcard -- uvx devcard-mcp

# Then in any Claude Code session:
> "Audit my GitHub profile @chiragxarora"
> "Generate my DevCard"
> "Make my repos agent-ready"
```

### Cursor
```json
// .cursor/mcp.json
{
  "mcpServers": {
    "devcard": {
      "command": "npx",
      "args": ["@devcard/mcp-server"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    }
  }
}
```

### VS Code + Copilot
```json
// .vscode/mcp.json
{
  "servers": {
    "devcard": {
      "command": "npx",
      "args": ["@devcard/mcp-server"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    }
  }
}
```

### Windsurf
```json
// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "devcard": {
      "command": "npx",
      "args": ["@devcard/mcp-server"]
    }
  }
}
```

### Docker (universal)
```bash
docker run -i --rm -e GITHUB_TOKEN=ghp_xxx ghcr.io/devcard/mcp-server
```

### Standalone CLI (for people who just want the tool)
```bash
# Install
pip install devcard
# or
pipx install devcard

# Use
devcard audit chiragxarora
devcard generate torvalds --format svg
devcard fix chiragxarora --token ghp_xxx
```

---

## Implementation Phases

### Phase 0: Scaffold + Schema (Days 1-2)
- [ ] Project setup with `uv`, pyproject.toml
- [ ] MCP server skeleton using official `mcp` Python SDK
- [ ] devcard.v1.schema.json (formal JSON Schema)
- [ ] Pydantic models for all DevCard sections
- [ ] GitHub API client (async httpx, rate limiting, diskcache)
- [ ] 3 example devcard.json files (handcrafted)
- [ ] Our own AGENTS.md (dogfooding from day 1)

### Phase 1: Core Engine (Days 3-8)
All extractors — each returns a Pydantic model, each is async:
- [ ] identity.py — profile info extraction
- [ ] languages.py — weighted language analysis across repos
- [ ] stack.py — dependency file parsing + mappings/dependencies.yaml
- [ ] activity.py — commit patterns, heatmap, streaks
- [ ] projects.py — repo ranking + classification
- [ ] quality.py — test/CI/docs/license detection
- [ ] collaboration.py — external PRs, orgs, contribution style
- [ ] expertise.py — domain inference from topics + deps

All analyzers:
- [ ] developer_type.py — classify dev archetype
- [ ] project_classifier.py — classify repos
- [ ] contribution_style.py — maintainer/contributor/solo/explorer
- [ ] scoring.py — human visibility + agent readiness scores
- [ ] issue_detector.py — find all issues in a profile

### Phase 2: MCP Tools — Audit + Generate (Days 9-13)
- [ ] `audit_profile` tool — full scoring + issue detection
- [ ] `generate_devcard` tool — create devcard.json
- [ ] `analyze_repo` tool — deep-dive single repo
- [ ] `compare_devs` tool — side-by-side comparison
- [ ] `render_card` tool — SVG card generation
- [ ] Wire all tools into MCP server with proper schemas
- [ ] Test with Claude Code: "audit my github" works end-to-end

### Phase 3: MCP Tools — Fix + Agent-Ready (Days 14-19)
- [ ] description_generator.py — generate repo descriptions from README/code
- [ ] topic_suggester.py — infer topics from language, deps, README
- [ ] agents_md_generator.py — generate AGENTS.md from code structure
- [ ] llms_txt_generator.py — generate llms.txt from docs
- [ ] profile_readme_generator.py — generate profile README with DevCard
- [ ] devcard_deployer.py — deploy devcard.json + SVG to profile repo
- [ ] `fix_profile` tool — preview + apply profile fixes
- [ ] `fix_repo` tool — preview + apply repo fixes
- [ ] `agent_ready` tool — one-command agent-readiness
- [ ] Dry-run mode for all fix tools
- [ ] Test with Claude Code: "make my repos agent-ready" works e2e

### Phase 4: Visual Layer + Themes (Days 20-23)
- [ ] SVG card renderer (Jinja2 templates)
- [ ] 5 themes: default, dark, minimal, neon, terminal
- [ ] Gallery: pre-generate cards for 30+ famous developers
- [ ] Card embeddable in GitHub READMEs (no foreignObject)

### Phase 5: Agent Skills + Distribution (Days 24-28)
- [ ] Claude Code skill (.claude/commands/devcard.md)
- [ ] Cursor rules (.cursor/rules/devcard.mdc)
- [ ] Copilot agent instructions
- [ ] Conversion script (one source → all formats)
- [ ] npx wrapper for easy MCP installation
- [ ] Docker image published to ghcr.io
- [ ] PyPI package published
- [ ] GitHub Action for automated maintenance
- [ ] Submit to awesome-mcp-servers registry
- [ ] Submit to awesome-claude-code-toolkit
- [ ] Submit to TokRepo skill registry

### Phase 6: Launch (Days 29-32)
- [ ] README with embedded SVG gallery
- [ ] Docs: schema guide, agent integration guide, heuristics docs
- [ ] Blog post / HN submission
- [ ] Twitter/X thread with visual card comparisons
- [ ] Tag famous developers with their auto-generated cards

---

## How Auto-Fix Works Without LLM

The fixers use pure heuristics — no API calls needed:

**Description Generator:**
```python
def generate_description(repo_data):
    """Generate repo description from available signals."""
    signals = []

    # 1. If README exists, extract first meaningful paragraph
    if repo_data.readme:
        first_para = extract_first_paragraph(repo_data.readme)
        if first_para and len(first_para) < 200:
            return first_para

    # 2. Build from classification + language + stack
    classification = classify_repo(repo_data)  # "library", "app", "tool"
    language = repo_data.primary_language       # "Python"
    stack = extract_stack(repo_data)            # ["FastAPI", "Redis"]

    # "A Python library built with FastAPI and Redis"
    desc = f"A {language} {classification}"
    if stack:
        desc += f" built with {', '.join(stack[:3])}"

    # 3. Add topic context
    if repo_data.topics:
        desc += f" for {repo_data.topics[0].replace('-', ' ')}"

    return desc
```

**Topic Suggester:**
```python
def suggest_topics(repo_data):
    """Infer topics from language, deps, README, and repo name."""
    topics = set()

    # From language
    lang_topics = {
        "Python": ["python"],
        "TypeScript": ["typescript"],
        "Go": ["golang"],
        "Rust": ["rust"],
    }
    topics.update(lang_topics.get(repo_data.primary_language, []))

    # From dependencies
    dep_topics = {
        "fastapi": ["fastapi", "api", "web"],
        "react": ["react", "frontend", "web"],
        "langchain": ["langchain", "ai", "llm"],
        "pytorch": ["pytorch", "machine-learning", "deep-learning"],
    }
    for dep in repo_data.dependencies:
        topics.update(dep_topics.get(dep.lower(), []))

    # From README keywords
    readme_lower = (repo_data.readme or "").lower()
    keyword_topics = {
        "cli": "cli",
        "command line": "cli",
        "api": "api",
        "docker": "docker",
        "kubernetes": "kubernetes",
        "oauth": "oauth",
        "authentication": "authentication",
        "machine learning": "machine-learning",
        "web scraping": "web-scraping",
    }
    for keyword, topic in keyword_topics.items():
        if keyword in readme_lower:
            topics.add(topic)

    # From classification
    if repo_data.classification == "library":
        topics.add("library")
    elif repo_data.classification == "tool":
        topics.add("developer-tools")

    return sorted(topics)[:20]  # GitHub allows max 20 topics
```

**AGENTS.md Generator:**
```python
def generate_agents_md(repo_data):
    """Generate AGENTS.md from code analysis — no LLM."""
    sections = []

    # Project overview from README first paragraph
    sections.append(f"# AGENTS.md\n")
    sections.append(f"## Project Overview")
    sections.append(extract_first_paragraph(repo_data.readme) or
                    f"{repo_data.name} is a {repo_data.primary_language} "
                    f"{repo_data.classification}.")

    # Tech stack from deps
    sections.append(f"\n## Tech Stack")
    sections.append(f"- Language: {repo_data.primary_language}")
    for category, items in repo_data.stack.items():
        if items:
            sections.append(f"- {category.title()}: {', '.join(items)}")

    # Project structure from directory listing
    sections.append(f"\n## Project Structure")
    for dir_entry in repo_data.top_level_dirs:
        desc = infer_directory_purpose(dir_entry)
        sections.append(f"- `{dir_entry}/` — {desc}")

    # Development commands from config files
    commands = extract_dev_commands(repo_data)
    if commands:
        sections.append(f"\n## Development Commands")
        for cmd, desc in commands.items():
            sections.append(f"- `{cmd}` — {desc}")

    # Contributing guidelines
    sections.append(f"\n## Contributing")
    if repo_data.has_tests:
        sections.append(f"- All PRs should include tests")
    if repo_data.has_ci:
        sections.append(f"- CI must pass before merge")
    if repo_data.has_linter:
        sections.append(f"- Code must pass linting")

    return "\n".join(sections)
```

---

## The GitHub Action (Continuous Maintenance)

```yaml
# .github/workflows/devcard.yml
name: Update DevCard
on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly on Sunday
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate DevCard
        uses: devcard/action@v1
        with:
          username: ${{ github.repository_owner }}
          token: ${{ secrets.GITHUB_TOKEN }}
          outputs: devcard.json,devcard.svg
          theme: dark

      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "chore: update devcard [skip ci]"
          file_pattern: devcard.json devcard.svg
```

---

## Distribution Checklist

### Registries to submit to (day 1 after launch):
- [ ] awesome-mcp-servers (84k+ stars)
- [ ] awesome-claude-code-toolkit
- [ ] awesome-claude-skills (52k+ stars)
- [ ] TokRepo (500+ indexed assets)
- [ ] MCP Registry (Anthropic official)
- [ ] npmjs.com (@devcard/mcp-server)
- [ ] PyPI (devcard)
- [ ] GitHub Marketplace (Action)
- [ ] Smithery.ai (MCP directory)

### Content for launch:
- [ ] Gallery of 30+ famous developer cards (SVG)
- [ ] "Before/After" audit screenshots
- [ ] 30-second demo GIF in README
- [ ] Blog post: "Your GitHub Is Invisible to AI Agents. Here's How to Fix It."
- [ ] Tweet thread comparing famous developers' DevCards
- [ ] HN post: "Show HN: DevCard – Make your GitHub agent-ready (MCP server)"

---

## Agent Prompt to Build This

```markdown
# Task: Build DevCard MCP Server

You are building **DevCard** — an MCP server that lets AI coding agents
audit, generate, fix, and maintain GitHub developer profiles for both
human visibility and AI agent readability.

## What this is:
An MCP server (Python, using the official `mcp` SDK) that exposes 8 tools:
audit_profile, generate_devcard, analyze_repo, fix_profile, fix_repo,
agent_ready, compare_devs, render_card.

Agents like Claude Code, Cursor, and Copilot install it with one command
and can then audit/fix any developer's GitHub presence.

## Core principles:
- **ZERO LLM by default** — all extraction and fixing uses GitHub API + heuristics
- **MCP-first** — the MCP server IS the product, CLI is secondary
- **Dry-run before apply** — all fix tools preview changes before applying
- **Agent-native** — designed to be called by agents, not humans directly
- **Apache 2.0 license**

## Tech stack:
- Python 3.11+, `mcp` SDK for MCP server
- `httpx` for async GitHub API, `pydantic` v2 for models
- `diskcache` for caching, `jinja2` for SVG templates
- `typer` + `rich` for optional CLI
- Optional: `litellm` for LLM enrichment
- Package via `uv`, publish to PyPI + npm (npx wrapper)

## Build order:

### 1. MCP Server Scaffold
Set up the MCP server using the official Python SDK (`mcp`).
Register all 8 tools with proper JSON schemas for inputs/outputs.
The server should work over both stdio (for Claude Code/Cursor)
and HTTP (for remote usage).

Entry point: `src/devcard/server.py`

```python
from mcp.server import Server
from mcp.types import Tool

server = Server("devcard")

@server.tool()
async def audit_profile(username: str, token: str = None) -> dict:
    ...

@server.tool()
async def generate_devcard(username: str, include_svg: bool = True) -> dict:
    ...
# etc.
```

### 2. GitHub API Client
Build `src/devcard/github/client.py`:
- Async httpx with connection pooling
- Rate limit handling (respect X-RateLimit headers, sleep when needed)
- diskcache with 1hr TTL
- Support unauthenticated (60/hr) and token auth (5000/hr)
- Token from tool input, GITHUB_TOKEN env var, or gh CLI

### 3. Extractors (async, each returns pydantic model)
Build in src/devcard/extractors/:
- identity.py, languages.py, stack.py, activity.py,
  projects.py, collaboration.py, quality.py, expertise.py

stack.py is the hardest — it parses dependency files from GitHub
Contents API (base64 decoding), handles package.json, requirements.txt,
pyproject.toml, go.mod, Cargo.toml, Gemfile, pom.xml, composer.json.
Maps deps via mappings/dependencies.yaml (400+ entries).

### 4. Analyzers
- developer_type.py — decision tree classification
- project_classifier.py — repo type heuristics
- scoring.py — human visibility (0-100) + agent readiness (0-100) scores
- issue_detector.py — find all fixable issues in a profile

### 5. MCP Tools: Audit + Generate
Wire extractors + analyzers into:
- audit_profile tool (returns scores + issues + recommendations)
- generate_devcard tool (returns full devcard.json + optional SVG)
- analyze_repo tool (deep-dive single repo)
- compare_devs tool (side-by-side comparison)

### 6. Fixers
Build in src/devcard/fixers/:
- description_generator.py — generate descriptions from README/code
- topic_suggester.py — infer topics from deps + language + keywords
- agents_md_generator.py — generate AGENTS.md from code structure
- llms_txt_generator.py — generate llms.txt from docs
- profile_readme_generator.py — generate profile README with DevCard
- devcard_deployer.py — deploy devcard.json + SVG to profile repo

ALL fixers work WITHOUT LLM by default. Pure heuristics.

### 7. MCP Tools: Fix + Agent-Ready
Wire fixers into:
- fix_profile tool (dry_run mode, then apply)
- fix_repo tool (dry_run mode, then apply)
- agent_ready tool (one-command full agent-readiness)

Fix tools use GitHub API to:
- Create files (Contents API)
- Update repo descriptions (Repos API)
- Update topics (Topics API)

### 8. SVG Card Renderer
Jinja2-based SVG templates. 5 themes. GitHub-README-compatible
(no foreignObject, no external fonts, no scripts).

### 9. Agent Skills
Create skill files in skills/:
- skills/claude-code/devcard.md
- skills/cursor/devcard.mdc
- skills/copilot/devcard-agents.md
- skills/convert.sh

### 10. Distribution
- npx wrapper: publish @devcard/mcp-server to npm
- PyPI: publish devcard package
- Docker: publish to ghcr.io
- GitHub Action in action/
- README with gallery, install instructions, demo GIF

## Key technical requirements:
- All extractors run concurrently (asyncio.gather)
- Graceful degradation — missing data = null, not crash
- Comprehensive error messages in tool responses
- SVG cards must be <50KB, self-contained, no external resources
- All fix tools have dry_run mode (preview before apply)
- Cache GitHub API responses for 1 hour
- Tests with pytest using fixture-based mock API responses
```

---

## Why This Wins

| Advantage | Explanation |
|---|---|
| **Zero friction adoption** | One command: `claude mcp add devcard -- npx @devcard/mcp-server` |
| **Agent does the work** | Developer says "fix my github", agent handles everything |
| **Novel angle** | "Agent readiness scoring" doesn't exist yet — we define the category |
| **Multiple distribution channels** | MCP registries, skill directories, npm, PyPI, GitHub Marketplace |
| **Dogfoods itself** | Our own repo has AGENTS.md, devcard.json, llms.txt — proof of concept |
| **No LLM dependency** | Works without API keys, free forever, deterministic results |
| **Viral visual layer** | SVG cards in READMEs = organic discovery |
| **Compounding moat** | dependencies.yaml gets richer with every contributor |

---

*DevCard MCP Server Plan — Built for the agent-native era.*
*Apache 2.0 · April 2026*