Loading Buffalo Projects
Loading Buffalo Projects
Developer reference
One write path, two front doors. The CLI and the buffalo-projects-mcp package share the same project schema and owner-authenticated APIs, so anything you can do from the terminal, your agent can do too. Every public page also exposes a machine-readable record at /b/{handle}/json.
On this page
Install
Use the CLI for the terminal and CI. Use the MCP package to let Claude, Cursor, or any MCP-compatible host write into the same record. Both authenticate the same way.
CLI
# Install the CLI npm i -g buffalo-projects # Connect your account (or set BUFFALO_TOKEN for CI/MCP) buffalo login # Log one private work-record update from the current repo buffalo init buffalo log "Shipped the first private work-record update"
MCP client config
// ~/.claude/mcp.json
{
"mcpServers": {
"buffalo": {
"command": "npx",
"args": ["-y", "buffalo-projects-mcp@latest"],
"env": {
"BUFFALO_TOKEN": "bp_your_api_key",
"BUFFALO_BASE_URL": "https://buffaloprojects.com"
}
}
}
}Both packages are open source — read the source before you install at github.com/rhinehart514/buffalo-projects-tools.
Authentication
Public reads need nothing. Owner writes need a builder API key. Run buffalo login for interactive use, or set BUFFALO_TOKEN (and optionally BUFFALO_BASE_URL) for CI and MCP. The same token authorizes both the CLI and the MCP server.
Read & write
The boundary is the same everywhere — the JSON twin, the CLI, and the MCP server. Anyone can read a public record without a token. Anything that changes a record needs the builder’s own key, and nothing publishes without explicit approval.
Read · no auth
Fetch any public page’s JSON twin at /b/{handle}/json, or start from the corpus-level /llms.txt. No token, no scrape, no login. A page that returns 404 without a token is intentionally private — treat it as not-public.
Write · builder token
The CLI and the buffalo-projects-mcp server use the same BUFFALO_TOKEN to scan, draft, and write work back. Scan and discovery never publish on their own — the builder approves specific candidates before anything is created.
CLI reference
Run buffalo with no arguments for inline help. Add --json to any command for machine-readable output.
Setup
buffalo init [--template <type>]Create a project.md in the current repo from a track template.
buffalo new --from <example-id>Start a new project.md from a worked example.
buffalo loginConnect your Buffalo Projects account and store a token locally.
buffalo authShow the connected account, or whether BUFFALO_TOKEN is set.
buffalo config [get | set <key> <value>]Read or write local CLI configuration.
Author work
buffalo log <what you shipped> [--note] [--project]Append a work entry to your log straight from the terminal.
buffalo add milestone <title> [--note]Record a dated milestone on the current project.
buffalo add evidence <file-or-url> [--caption] [--milestone]Attach an inspectable source — repo, link, doc, or screenshot.
buffalo capture [--days <n>] [--accept <id,id|all>]Turn recent local activity into proposed work entries.
Discover & lint
buffalo scan [--days <n>] [--dry-run] [--yes]Detect distinct projects in the codebase worth adding.
buffalo examples <type>Print high-density worked examples for a track.
buffalo lint [project.md]Run the density rubric and list addressable gaps.
Sync
buffalo statusShow local vs. hosted state for the current project.
buffalo diff [--remote <path>]Show what a push would change on the hosted record.
buffalo previewRender the project.md as it will appear once pushed.
buffalo push [--remote <path>] [--force]Write the local project.md to your hosted record.
buffalo pull [--remote <path>] [--force]Pull the hosted record back into local project.md.
buffalo ci [--push]Lint, then optionally push — built for CI pipelines.
MCP tools
Read-only tools work from local context. Writes require a token. Scan and discovery tools never publish on their own — the builder approves specific candidates before anything is created.
Account
buffalo.auth_statusCheck whether the server has a connected builder account and return setup instructions.
Draft & density
buffalo.draft_projectCreate a structured project draft from a conversational description.
buffalo.check_densityReturn density dimensions and addressable gaps for a project or project.md body.
buffalo.lint_sectionRun density feedback against one project.md section.
buffalo.suggest_evidenceSuggest inspectable evidence from context without attaching anything.
buffalo.compare_to_examplesCompare a draft to high-density examples for its track.
Work log
buffalo.log_workPersist a work entry to the authenticated log. Retry-safe, with optional source URL. (buffalo.save_work is a deprecated alias.)
buffalo.list_workRead recent work entries before summarizing or updating.
buffalo.get_work_summarySummarize recent work by source, active day, and latest entries.
buffalo.preview_work_entryPreview project.md with a dated work entry appended. Nothing is saved.
Projects
buffalo.list_projectsRead the authenticated builder's projects from the hosted API.
buffalo.get_projectRead one project by ID.
buffalo.add_projectsPersist chosen scan candidates as link-only projects (publishing stays explicit).
buffalo.update_projectAdd detail to a project — description, skills, current ask, proof, evidence, repo.
Scan & discovery
buffalo.scan_repoScan one local codebase and propose distinct projects. Read-only.
buffalo.find_projectsScan approved roots, dedupe against the account, and return a redacted preview.
buffalo.preview_project_writesShow exactly what fields would be sent before add_projects. Redacts local paths.
buffalo.refresh_projectsRescan approved roots and propose project updates or private work entries.
buffalo.ignore_projectsAdd candidates to the remote never-list so they stop reappearing in scans.
Briefs, graph & validation
buffalo.build_resume_briefBuild a resume-quality builder brief from approved local metadata.
buffalo.build_evidence_graphBuild the evidence graph: projects, skills, claims, evidence, confidence, proof gaps.
buffalo.suggest_next_proofSuggest the next proof moves that make a builder profile more credible.
buffalo.request_vouchCreate a vouch request link after meaningful work is logged.
Routing
buffalo.match_opportunitiesMatch a builder's record against the aggregated public Buffalo opportunity corpus (events, grants, programs) — the one opportunity-listing verb. Public supply only — no seeded marketplace or placement guarantees. (buffalo.match_targets is a deprecated alias.)
MCP prompts
Prompts orchestrate the tools above into a complete task, from first-run inventory to a weekly update.
buffalo:onboardingCheck auth, explain local-first discovery, and guide token setup.
buffalo:first-run-inventoryAsk which local roots are approved, scan them, and create only approved projects.
buffalo:intakeGuide a builder from rough notes to a project draft. Ask for evidence first.
buffalo:resume-briefBuild a resume-quality brief from approved local project metadata.
buffalo:evidence-graphConnect projects, skills, claims, evidence, and proof gaps.
buffalo:proof-gapsFind the next proof moves: missing evidence, unclear outcomes, stale activity.
buffalo:post-hackathonCapture the minimum durable record after an event: what shipped, who, what proof.
buffalo:prep-for-recruiterStrengthen a project for external review: clarity, evidence, outcomes, current ask.
buffalo:weekly-updateAsk what shipped, what changed, what evidence appeared, what milestone to log.
MCP resources
Resources are read-only context the host can load directly.
buffalo://schema/projectZod-derived JSON schema for a project record.
buffalo://templates/{type}Starter project.md templates by track.
buffalo://examples/{type}Worked examples of shipped projects by track.
buffalo://rubricDensity-scoring rubric used to grade builder pages.
JSON twin
Each public page links an alternate JSON document agents can consume directly — agent brief, trust graph, project evidence, public work log, and the interfaces available for deeper authenticated writes.
GET /b/{handle}
<link rel="alternate" type="application/json"
href="/b/{handle}/json" />Connect the CLI or the MCP server once, and your record stays current every time you log work — no manual editing.