FedSpeak

Federal Acronym Decoder — Decode and encode U.S. government acronyms from text or single lookups.

FedSpeak is a REST API, interactive website, and npm package that expands 1,157 federal government acronyms with full names, descriptions, agency context, and category classifications.

Website: fedspeak.dev

Features

• Decode — Send any acronym, get the full expansion with description, agency, and category
• Encode — Send a full name, get the acronym back
• Text Scanning — Paste a block of text, FedSpeak finds and decodes every recognized acronym
• 1,157 Acronyms — Departments, agencies, cybersecurity, NIST, CMMC, procurement, contract vehicles, legislation, and more
• REST API — GET and POST support, JSON responses, CORS enabled
• npm Package + CLI — Use the decoder in Node.js, or run npx fedspeak GSA from a shell
• MCP Server — Remote endpoint at fedspeak.dev/mcp plus a fedspeak-mcp stdio binary, so Claude, ChatGPT, Cursor, and other agents can call it
• Interactive Demo — Try it live at fedspeak.dev

Quick Start

API

# Decode an acronym
curl -X POST https://fedspeak.netlify.app/api/decode \
  -H "Content-Type: application/json" \
  -d '{"acronym": "DOD"}'

# Scan text for acronyms
curl -X POST https://fedspeak.netlify.app/api/decode \
  -H "Content-Type: application/json" \
  -d '{"text": "The DOD and GSA are working with OMB on the new RFP"}'

# Encode a full name to its acronym
curl -X POST https://fedspeak.netlify.app/api/encode \
  -H "Content-Type: application/json" \
  -d '{"name": "General Services Administration"}'

npm Package

npm install fedspeak
# or
npm install @metaphase-tech/fedspeak

import { lookupAcronym, scanText, decode, encode, getAcronymCount } from 'fedspeak';

// Single lookup
const result = lookupAcronym('DOD');
console.log(result?.full); // "Department of Defense"

// Scan text for all acronyms
const found = scanText('The DOD and GSA are working with OMB');
found.forEach(r => console.log(`${r.acronym} = ${r.full}`));

// Full decode with response envelope
const response = decode({ text: 'Submit the RFP to the CO at GSA' });
console.log(response.results); // [{ acronym: 'RFP', ... }, { acronym: 'CO', ... }, { acronym: 'GSA', ... }]

// Reverse lookup: full name to acronym
const encoded = encode({ name: 'General Services Administration' });
console.log(encoded.results[0].acronym); // "GSA"

// Total count
console.log(getAcronymCount()); // 1156

MCP Server (AI agents)

FedSpeak is a Model Context Protocol server. Tools: decode_acronym, scan_text, encode_name, list_acronyms. Resources: fedspeak://agencies, fedspeak://categories.

# Remote (Streamable HTTP, stateless, no auth)
claude mcp add --transport http fedspeak https://fedspeak.dev/mcp

# Local over stdio
npx -y -p @metaphase-tech/fedspeak fedspeak-mcp

{ "mcpServers": { "fedspeak": { "url": "https://fedspeak.dev/mcp" } } }

Agent-oriented overview at fedspeak.dev/llms.txt.

CLI

npx fedspeak GSA                                   # one acronym
npx fedspeak DOW OMB CISA                          # several
npx fedspeak --text "The GSA and OMB released the RFP"   # scan a passage
npx fedspeak --encode "General Services Administration"  # name → acronym
npx fedspeak GSA --json                            # machine-readable

Exit code is 1 when any requested acronym is not found, 2 for usage errors. fedspeak --help lists all options.

API Reference

Decode

POST /api/decode
GET  /api/decode?acronym=GSA
GET  /api/decode?text=The+DOD+and+GSA+work+with+OMB

Single lookup request:

{ "acronym": "GSA" }

Text scan request:

{ "text": "The DOD and GSA are working with OMB on the new RFP" }

Response:

{
  "success": true,
  "query": "GSA",
  "mode": "single",
  "results": [{
    "acronym": "GSA",
    "full": "General Services Administration",
    "description": "Federal agency managing government buildings, procurement, and technology solutions.",
    "agency": "GSA",
    "category": "agency",
    "url": "https://www.gsa.gov"
  }],
  "count": 1,
  "truncated": false
}

Encode

POST /api/encode
GET  /api/encode?name=General+Services+Administration
GET  /api/encode?text=The+Department+of+Defense+is+working+with...

Single lookup request:

{ "name": "General Services Administration" }

Text scan request:

{ "text": "The Department of Defense and General Services Administration..." }

npm Package API

Functions

Function	Description
lookupAcronym(query)	Look up a single acronym. Returns DecodedResult or null
scanText(text)	Scan text for all recognized acronyms. Returns DecodedResult[]
decode(request)	Full decode with response envelope ({ acronym } or { text })
lookupName(query)	Reverse lookup: full name to acronym. Returns EncodedResult or null
scanTextForNames(text)	Scan text for full names, return their acronyms. Returns EncodedResult[]
encode(request)	Full encode with response envelope ({ name } or { text })
getAllAcronyms()	Get sorted array of all acronym keys
getAcronymCount()	Get total number of acronyms in the database
truncateResponse(response)	Truncate response to fit 2000-char limit

TypeScript Types

import type {
  AcronymCategory,  // 'department' | 'agency' | 'office' | 'bureau' | 'program' | 'process' | 'regulation' | 'system' | 'general'
  AcronymEntry,     // { full, description, agency, category, url?, aliases? }
  AcronymData,      // Record of acronym key to AcronymEntry
  DecodedResult,    // Single decode result
  DecodeResponse,   // Full decode response envelope
  DecodeRequest,    // { acronym?: string; text?: string }
  EncodedResult,    // Single encode result
  EncodeResponse,   // Full encode response envelope
  EncodeRequest,    // { name?: string; text?: string }
} from 'fedspeak';

Acronym Coverage

1,157 entries across these categories:

Category	Examples
Federal departments	DOD, DOJ, DOE, HHS, DHS, VA, DOS, DOT, ...
Agencies & offices	NASA, GSA, EPA, SBA, CISA, NIST, OPM, FEMA, ...
Cybersecurity & NIST	CMMC, FedRAMP, FISMA, CVE, CVSS, ZTA, ATT&CK, CSF, ...
Identity & auth	IAL, AAL, FAL, MFA, FIDO, PIV, CAC, SSO, ...
Procurement & acquisition	FAR, DFARS, GWAC, IDIQ, BPA, RFP, CO, COR, ...
Contract vehicles	OASIS+, CIO-SP4, SEWP VI, 8(a) STARS III, ALLIANT 2, ...
Legislation	FITARA, FOIA, APA, NEPA, HIPAA, FISMA, ACA, ...
IT & systems	FedRAMP, ATO, HSPD-12, eMASS, Login.gov, ...
Budget & finance	OMB, CBO, GAO, PPBE, CR, ...
HR & personnel	OPM, GS, SES, USERRA, ...

Development

Prerequisites

• Node.js 22+ (.nvmrc)
• npm 10+

Setup

git clone https://github.com/MetaPhase-Consulting/fedspeak.git
cd fedspeak
npm install

Commands

Command	Description
npm run dev	Start Vite dev server
npx netlify dev	Full local dev with API at localhost:8888
npm run build	Production build
npm run lint	ESLint
npm run typecheck	TypeScript strict check
npm run test:run	Run tests once
npm run test	Run tests in watch mode
npm run test:coverage	Run tests with coverage

Project Structure

fedspeak/
├── netlify/functions/       Serverless API endpoints
│   ├── decode.ts            POST /api/decode
│   ├── encode.ts            POST /api/encode
│   └── mcp.ts               POST /mcp (MCP Streamable HTTP)
├── src/
│   ├── shared/              Core logic (shared by API, website, npm package)
│   │   ├── decoder.ts       lookupAcronym(), scanText(), decode()
│   │   ├── encoder.ts       lookupName(), scanTextForNames(), encode()
│   │   ├── mcp-server.ts    createFedSpeakServer() — MCP tools and resources
│   │   ├── truncate.ts      Response truncation
│   │   ├── types.ts         TypeScript interfaces
│   │   └── data/
│   │       └── acronyms.json
│   ├── components/          React UI components
│   └── pages/               React Router pages
├── cli-package/             npm package: library, `fedspeak` CLI, `fedspeak-mcp` server
├── tests/                   Vitest test suites
├── public/                  openapi.json, llms.txt, robots.txt, sitemap.xml
└── .github/workflows/       CI/CD pipelines

Tech Stack

Layer	Choice
Runtime	Node.js 22, TypeScript 5.9
API	Netlify Functions v2 (serverless)
Data	Static JSON (no database)
Website	Vite 8 + React 19 + Tailwind CSS 4 + React Router 8
Testing	Vitest + @vitest/coverage-v8
CI/CD	GitHub Actions
Deploy	Netlify

Adding Acronyms

Add entries to src/shared/data/acronyms.json in alphabetical order:

"ACRONYM": {
  "full": "Full Name",
  "description": "Brief description (1-2 sentences).",
  "agency": "Parent agency acronym or General",
  "category": "department|agency|office|bureau|program|process|regulation|system|general",
  "url": "https://optional-official-website.gov",
  "aliases": ["optional", "alternate", "spellings"]
}

Contributing

1. Fork the repository
2. Create a feature branch from dev
3. Make your changes
4. Ensure npm run lint, npm run typecheck, and npm run test:run all pass
5. Open a PR to dev

Branching

• dev — Default branch, active development
• main — Production, deploys to Netlify
• Feature branches merge into dev via PR
• dev merges into main via PR for releases

License

MIT © MetaPhase