This is the Hacker News MCP server from universal-mcp-toolkit, which lets you browse and search Hacker News content programmatically. No authentication is required.
Get top stories (get_top_stories): Retrieve the current top Hacker News stories with a configurable limit (1–30, default 10), returning each story's id, title, URL, author, score, comment count, publication date, and text.
Search stories (search_stories): Search Hacker News stories by keyword query with a configurable result limit (1–30, default 10), returning the same rich story metadata.
Get item thread (get_item_thread): Fetch a specific Hacker News story along with its full nested comment thread, with controls for recursion depth (1–6, default 2) and maximum children per node (1–50, default 20), returning story details plus a recursive tree of replies with author, text, and timestamps.
Provides tools for searching scientific papers and managing reading lists on the arXiv platform.
Enables management of Cloudflare Workers, routes, and edge rollouts.
Allows for the inspection and management of Docker containers, images, and daemon state.
Facilitates interaction with GitHub repositories, pull requests, workflows, and search features.
Provides tools for managing calendars, events, and meeting workflows.
Enables searching, metadata management, and file exports within Google Drive.
Allows managing Jira tickets, workflow transitions, and incident triage.
Facilitates issue triage and project planning within Linear.
Enables operations on MongoDB collections, including document reads and aggregations.
Provides tools for managing Notion pages, databases, and structured documents.
Allows searching the npm registry and accessing package metadata, versions, and dist-tags.
Facilitates schema inspection and executing guarded queries on PostgreSQL databases.
Provides tools for managing Redis keys, TTLs, and cache diagnostics.
Enables interaction with Slack channels, messaging, and message history.
Allows for playback control, search, and playlist management on Spotify.
Facilitates management of Stripe customers, invoices, and subscriptions.
Provides tools for interacting with Supabase tables, storage, and project settings.
Enables management of Vercel projects, deployments, and environment variables.
The canonical open-source monorepo for production-ready Model Context Protocol servers.
If you have ever wanted one place to find great MCP servers for GitHub, Slack, Notion, databases, cloud platforms, research sources, and local files without stitching together a dozen half-finished repos, this is it.
universal-mcp-toolkit is one of three sibling projects that compose into a complete agent memory + tooling stack:
Project | Role |
MCP protocol, server registry, and tool routing | |
Graph-based persistent memory across agent sessions | |
Token-cost guardian that compresses prompts and injects MemOS memory slices |
Together they cover transport + tools (UMT), memory + persistence (MemOS), and LLM inference cost control (llm-guardian). The MemOS MCP adapter is published as @mem-os/sdk and pairs directly with UMT's link memos command.
Related MCP server: Slack MCP Server by CData
The fastest way to get going:
# See all 27 available servers
npx universal-mcp-toolkit list
# Interactive setup — pick your servers, choose transport, write config
npx universal-mcp-toolkit install
# Generate a Claude Desktop config snippet
npx universal-mcp-toolkit config --server github slack filesystem --target claude-desktop
# Run a server locally
npx universal-mcp-toolkit run github --transport stdio
# Check your environment before debugging
npx universal-mcp-toolkit doctor github
# Validate a reviewable cross-server workflow
npx universal-mcp-toolkit workflow validate examples/workflows/github-search-to-slack.jsonFor a guided setup walkthrough, open docs/getting-started.html. For deterministic composition, see docs/workflows.md.
Or install globally:
npm install -g universal-mcp-toolkit
umt listOr install from CodeGuilds — the community registry for AI developer tools:
codeguilds install universal-mcp-toolkitThe MCP ecosystem is exploding, but the developer experience is still fragmented.
Most repos solve one narrow integration.
Many servers stop at a demo-quality tool or two.
Transport support, auth handling, docs, and packaging are wildly inconsistent.
There is no obvious reference implementation that shows how a serious MCP monorepo should feel.
universal-mcp-toolkit fixes that with one opinionated, high-quality Turborepo:
28 production-focused MCP servers
One shared strict-mode TypeScript core
One polished CLI for install, config, run, and diagnostics
Consistent Zod validation, structured errors, and pino logging
Stdio plus HTTP+SSE support across the toolkit
Discovery-friendly .well-known/mcp-server.json server cards
Tool discovery — umt tools list finds any MCP tool across 27+ servers by name or category
Deterministic workflows — umt workflow validate|run executes reviewable, versioned JSON workflows with strict input and step references
Server composition — umt compose remains available for quick two-step output piping
Standards-aligned discovery — umt discover --registry reads official MCP Registry-compatible endpoints alongside local and well-known discovery
Enforced tool boundaries — bridge allowlists and RBAC policies are checked before cache lookup, reconnect, or remote execution
TTL + LRU caching — MCPFunctionCallingBridge caches results by tool+args, avoiding redundant API calls
Health monitoring — transport failures feed the circuit breaker without treating ordinary tool validation errors as connection failures
Buffered result chunks — callToolStreaming() exposes completed results through an async chunk iterator; it does not claim protocol-level streaming
Multi-server sessions — Session class orchestrates tools across multiple MCP servers with parallel calls
Lazy plugin loading — server packages loaded on-demand, not statically bundled
Lazy tool registration — registerLazyTool defers expensive initialization until a tool is actually called
Structured error context — bridge errors include tool name, args, and error type for easier debugging
Type-safe chaining — callToolChain with ToolChain types enables compile-time-checked tool pipelines
Real developer utility right now
Great default ergonomics for Claude Desktop, Cursor, and local workflows
A single architecture you can learn once and extend everywhere
Strong package hygiene with exports maps, keywords, build scripts, and test hooks
A repo designed to be both a product and a reference implementation
Category | What you get |
Core runtime |
|
Unified CLI |
|
Collaboration servers | GitHub, Notion, Slack, Linear, Jira, Discord, Trello |
Productivity servers | Google Calendar, Google Drive |
Media and commerce servers | Spotify, Stripe |
Data servers | PostgreSQL, MongoDB, Redis, Supabase, Airtable |
Platform servers | Vercel, Cloudflare Workers, Docker, npm Registry |
Research and local servers | Hacker News, arXiv, FileSystem |
Memory server | MemOS local persistent memory |
Experimental companion packages under the @contextcore/* scope currently include Notion, Slack, Playwright, and OpenAI variants used for a separate publish line and testing lane.
Option | Breadth | DX quality | Shared architecture | Host config help | Documentation polish | Tool discovery | Server composition | Caching | Lazy loading | Remote MCP discovery | Resilient transport | Token budgeting |
| 28 servers in one monorepo | High | Yes | Yes | Yes | ✅ | ✅ | ✅ TTL+LRU | ✅ | ✅ | ✅ Auto-reconnect + circuit breaker | ✅ |
Single-service MCP repos | Narrow | Varies | No | Rarely | Usually none | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
Personal one-off scripts | Very narrow | Low | No | No | No | Usually none | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
Server | Focus | Primary required env |
GitHub | Repositories, pull requests, workflows, search |
|
Notion | Pages, databases, structured docs |
|
Slack | Channels, history, messaging |
|
Linear | Issue triage and planning |
|
Jira | Tickets, workflow transitions, incident triage |
|
Google Calendar | Calendars, events, meeting workflows |
|
Google Drive | Search, metadata, exports |
|
Spotify | Playback, search, playlists |
|
Stripe | Customers, invoices, subscriptions |
|
PostgreSQL | Tables, schema inspection, guarded queries |
|
MongoDB | Collections, document reads, aggregation |
|
Redis | Keys, TTLs, cache diagnostics |
|
Supabase | Tables, storage, project access |
|
Vercel | Projects, deployments, environments |
|
Cloudflare Workers | Workers, routes, edge rollouts |
|
Docker | Containers, images, daemon state | none required |
npm Registry | Search, metadata, versions, dist-tags | none required |
Hacker News | Top stories, search, threads | none required |
arXiv | Paper search and reading lists | none required |
FileSystem | Safe local file search, reads, writes |
|
MemOS | Local-first persistent memory over MCP | none required |
Discord | Guilds, channels, messages, members |
|
Airtable | Tables, records, CRUD operations |
|
Trello | Boards, lists, cards, archiving |
|
Playwright | Browser automation and web scraping |
|
OpenAI | Chat completions, embeddings, and model queries |
|
Some servers also expose optional tuning variables such as POSTGRESQL_ALLOW_WRITES, REDIS_ALLOW_WRITES, MONGODB_ALLOW_WRITE_PIPELINES, VERCEL_TEAM_ID, or FILESYSTEM_MAX_READ_BYTES. The root .env.example includes the most useful knobs.
The bundled list above is curated and dependency-pinned. Third-party MCP servers
can be added as opt-in entries using the same mcpServers config shape — just
point npx at the external package. They are not part of the default bundle.
@vynly/mcp)Vynly is a social network purpose-built for AI-generated
images and short video. Its MCP server (@vynly/mcp,
by @Vovala14) exposes a public posting API with a
free demo token on first call (no signup) and handles provenance verification
(C2PA / SynthID / generator EXIF) automatically — useful when you want an agent to
publish output anywhere with provenance baked in.
Opt-in only: Vynly is not bundled in the default config. Add it to your host config (Claude Desktop, Cursor, or any MCP client) as a normal
npxserver:
{
"mcpServers": {
"vynly": {
"command": "npx",
"args": ["-y", "@vynly/mcp"],
"env": {
"VYNLY_TOKEN": "${VYNLY_TOKEN}"
}
}
}
}Grab a free demo token (no signup) before first use:
curl -X POST https://vynly.co/api/agents/demo-tokenThen generate or merge the snippet with:
corepack pnpm --filter universal-mcp-toolkit exec umt config --server vynly --target claude-desktop --mode workspace(If umt does not yet know the vynly server id, paste the JSON above directly
into your host config — the runtime is the same npx -y @vynly/mcp launch.)
universal-mcp-toolkit/ ├─ packages/ │ ├─ core/ │ ├─ bridge/ │ └─ cli/ ├─ docs/ │ ├─ index.html │ └─ getting-started.html ├─ servers/ │ ├─ github/ │ ├─ notion/ │ ├─ slack/ │ ├─ linear/ │ ├─ jira/ │ ├─ google-calendar/ │ ├─ google-drive/ │ ├─ spotify/ │ ├─ stripe/ │ ├─ postgresql/ │ ├─ mongodb/ │ ├─ redis/ │ ├─ supabase/ │ ├─ vercel/ │ ├─ cloudflare-workers/ │ ├─ docker/ │ ├─ npm-registry/ │ ├─ hackernews/ │ ├─ arxiv/ │ ├─ discord/ │ ├─ airtable/ │ ├─ trello/ │ └─ filesystem/ ├─ turbo.json ├─ pnpm-workspace.yaml └─ README.md
## Quick start
### Clone and install
```bash
git clone https://github.com/Markgatcha/universal-mcp-toolkit.git
cd universal-mcp-toolkit
corepack pnpm installcorepack pnpm buildcorepack pnpm --filter universal-mcp-toolkit exec umt listcorepack pnpm --filter universal-mcp-toolkit exec umt config --server github slack filesystem --target claude-desktop --mode workspacecorepack pnpm --filter universal-mcp-toolkit exec umt run github --transport stdiocorepack pnpm --filter universal-mcp-toolkit exec umt doctor githubThe CLI is designed to feel like a real product, not a pile of scripts.
umt listSee every available server, grouped by category with required environment variables and descriptions.
umt configGenerate ready-to-paste JSON for Claude Desktop, Cursor, or any MCP-compatible host config flow.
umt installRun an interactive setup flow, choose servers, choose npx or workspace mode, write the result to disk, and save the profile for later reference.
umt runLaunch any built workspace server locally with stdio or HTTP+SSE transport.
The --supervise flag enables crash-loop detection and automatic restarts:
umt run github --transport stdio --superviseIf the server crashes 5 times within 60 seconds it stops retrying. Logs are written to the state directory under logs/<serverId>.log and can be tailed with umt logs <serverId>.
umt doctorCheck build output, config state, and required environment variables before you waste time debugging a missing token or missing dist file.
Command | What it does |
| Show currently running umt server processes and their PIDs |
| Tail the log file for a specific server |
| Run a live end-to-end MCP handshake test against a server |
| Check registry config and live stdio handshakes where local build output exists |
| Validate a versioned JSON workflow without starting any server |
| Execute a validated workflow sequentially and disconnect every step safely |
| Include official or private MCP Registry-compatible entries in discovery |
| Search available servers by name, description, and tags |
| Interactive setup wizard for new users |
| Check npm for a newer version of the CLI and optionally install it |
| Check npm for newer versions of individual server packages |
| Export install profiles to a portable JSON file (no secrets included) |
| Export current server config in a specific client format |
| Link a local MemOS/ContextCore SQLite memory database |
| Create a new named profile with interactive wizard |
| Show profile configuration details |
| Export a named profile to a JSON file |
| Import a profile from a JSON file |
Paste a generated snippet into your Claude Desktop config file. On Windows, that is commonly:
%APPDATA%\Claude\claude_desktop_config.jsonOn macOS, use ~/Library/Application Support/Claude/claude_desktop_config.json. On Linux, use ~/.config/Claude/claude_desktop_config.json.
The JSON examples below use literal placeholders like ${GITHUB_TOKEN}. Replace them with real values before pasting into your host config.
Example:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@universal-mcp-toolkit/server-github", "--transport", "stdio"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
},
"filesystem": {
"command": "npx",
"args": ["-y", "@universal-mcp-toolkit/server-filesystem", "--transport", "stdio"],
"env": {
"FILESYSTEM_ROOTS": "${FILESYSTEM_ROOTS}"
}
}
}
}Generate the same mcpServers snippet and place it into the MCP config file you use for Cursor. The CLI keeps the format host-friendly and consistent, so the same generated JSON works well as a reusable snippet:
{
"mcpServers": {
"slack": {
"command": "npx",
"args": ["-y", "@universal-mcp-toolkit/server-slack", "--transport", "stdio"],
"env": {
"SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
}
},
"linear": {
"command": "npx",
"args": ["-y", "@universal-mcp-toolkit/server-linear", "--transport", "stdio"],
"env": {
"LINEAR_API_KEY": "${LINEAR_API_KEY}"
}
}
}
}Every server in the toolkit is designed around the same transport story:
stdio for local child-process integrations
Streamable HTTP for current remote MCP integrations
HTTP+SSE retained as a legacy compatibility transport
discovery metadata exposed through package cards and Registry-compatible metadata
The shared core handles runtime bootstrapping, logging, env loading, and tool registration so every server behaves consistently.
UMT is discoverable through three complementary manifest paths so it shows up in registry search, Smithery, and direct well-known lookups:
Official MCP Registry — registry-server.json at the repo root uses the reverse-DNS name io.github.markgatcha.universal-mcp-toolkit and lists the tool surface, transports, and environment variables. Submit it to the official registry to appear in mcp-cli search results.
Smithery auto-discovery — .well-known/mcp/server-card.json is the well-known server card that Smithery (and any RFC-style crawler) fetches to build a live profile. Keep version and description in sync with packages/cli/package.json.
Runtime .well-known/mcp-server.json — the discovery document served by the running server; bumped to 1.6.28 with the updated registry description.
# Search the official MCP Registry together with local discoveries
umt discover --registry
# Use a private or alternate Registry-compatible endpoint
umt discover --registry https://registry.example.com/v0.1/servers
# Verify the well-known card is served correctly
curl http://localhost:3000/.well-known/mcp/server-card.json | jq .name@universal-mcp-toolkit/core is the part you will want to study if you are building your own MCP servers.
It includes:
ToolkitServer base class
defineTool<TInput, TOutput> helper
loadEnv() for strict configuration validation
HttpServiceClient for typed fetch-based integrations
createServerCard() for discovery metadata
validateIntegrationManifest() and summarizeIntegrationReadiness() for versioned integration evidence
parseRuntimeOptions() and runToolkitServer() for stdio and HTTP launch flows
pino logging configured for stderr-safe server operation
See docs/integration-contract.md for the additive integration contract and readiness model.
TypeScript strict mode across the workspace
Zod schemas for input and output validation
Explicit structured errors for config, validation, and upstream failures
Consistent package manifests with exports maps and keywords
Server cards under .well-known/
Turborepo orchestration for build, typecheck, test, and clean flows
This repo is meant to be the reference implementation developers point to when they ask:
What should a serious MCP monorepo look like?
How should server packages be documented and discovered?
How do you keep 20 integrations consistent without turning the codebase into a mess?
The answer should be: clone this repo, run the CLI, read the core package, and adapt the parts you need.
corepack pnpm install
corepack pnpm build
corepack pnpm typecheck
corepack pnpm testbun install
bun run build
bun run packages/cli/dist/index.js --versionUse Turbo filters when you only want to work on one package:
corepack pnpm --filter @universal-mcp-toolkit/core build
corepack pnpm --filter universal-mcp-toolkit typecheck
corepack pnpm --filter @universal-mcp-toolkit/server-github testIf you only want the onboarding path, start with docs/getting-started.html.
packages/coreShared runtime primitives and strict abstractions for server authors.
packages/bridgeConnect any MCP server to any LLM provider — OpenAI, Anthropic, or Ollama function-calling format. Includes health monitoring, circuit breakers, RBAC, audit logging, TTL+LRU caching, and a full agent conversation loop. Use with the Vercel AI SDK via @universal-mcp-toolkit/ai-sdk.
packages/ai-sdkAdapter that lets you use UMT's MCP tools directly with the Vercel AI SDK's streamText() and generateText() functions. Zero boilerplate — turn any MCP server into AI SDK tools in one line.
packages/cliThe operator console for listing, configuring, installing, running, and diagnosing the entire toolkit.
servers/*27 independently publishable MCP server packages that all share the same operational shape.
The monorepo is intentionally structured so it can grow without losing coherence.
Add more servers without inventing a new architecture every time
Improve server cards as discovery standards evolve
Expand host config templates as more MCP clients standardize their formats
Deepen smoke and contract tests across transports
Please read CODE_OF_CONDUCT.md before participating in issues, pull requests, reviews, or discussions. The project aims to stay both technically rigorous and welcoming to contributors at every experience level.
Pair universal-mcp-toolkit with MemOS for persistent, graph-based memory across agent sessions.
# Add persistent memory to your MCP agents
pip install memos
npm install @mem-os/sdk
# Generate a ready-to-paste MemOS MCP config
npx universal-mcp-toolkit link memos --db-path ~/.memos/memos.dbMemOS acts as the memory layer for your MCP stack — every tool call, result, and context your agent produces can be stored, retrieved, and searched across restarts and sessions. The MemOS MCP adapter runs through npx -y @mem-os/sdk mcp.
Layer | Tool | Role |
Transport & Tools | universal-mcp-toolkit | MCP protocol, server registry, tool routing |
Memory & Persistence | Graph-based persistent memory across sessions | |
LLM Inference | Ollama / any LLM | Local model execution |
Building something with universal-mcp-toolkit? We'd love to know.
Open a Discussion and tell us:
What you're building
Which servers you're using
Any integrations or workflows you've set up
You might get featured here.
Claude Desktop + GitHub + FileSystem — local dev assistant that reads repos and writes to disk
Cursor + PostgreSQL + Supabase — database-aware AI code completion
Paired with MemOS — persistent agent memory across sessions
If you've created a custom server, workflow, or integration using this toolkit as a base, open a PR to add it to the Wiki or start a Discussion. The best examples will be highlighted in the README.
Website: context-core.dev/umt
Discord: discord.gg/DyQGgPuueu — real-time help and release chatter
Twitter/X: @Context_Core
If UMT saves you from stitching together a dozen half-finished MCP repos, consider the star — it keeps the project visible.
MIT — see LICENSE for full terms.
Fetches Hacker News beststories ranking from the public Firebase API and returns summaries, unlike get_top_stories front-page rank or get_new_stories chronological rank. Read-only, idempotent, and unauthenticated; the client caches GET responses in memory for 60 seconds and throttles upstream HN/Algolia requests to 10 requests/second with a burst of 20, while upstream HTTP, rate-limit, or response-shape failures are returned as tool errors. Use for high-quality/popular stories beyond the current front page; use search_stories for topic discovery or get_item_thread for comments on one item.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of stories to return. Defaults to 10; valid range is 1 to 30. |
| Name | Required | Description |
|---|---|---|
| stories | Yes | |
| returned | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only, idempotent, unauthenticated nature, client-side caching for 60 seconds, throttling to 10 req/s with burst 20, and error handling for upstream failures. No annotations present, so description carries full burden and meets it comprehensively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purpose first, then behavioral details, then usage guidance. Slightly verbose but all sentences earn their place; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and presence of output schema, the description fully covers purpose, behavior, error handling, and usage differentiation. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter (limit) with its own description. The tool description adds no further semantic detail beyond the schema, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states it fetches Hacker News beststories ranking and returns summaries. Clearly distinguishes from siblings by contrasting with get_top_stories (front-page rank) and get_new_stories (chronological rank).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: use for high-quality/popular stories beyond current front page. Names alternatives: search_stories for topic discovery, get_item_thread for comments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches one Hacker News item by numeric itemId and expands its nested comment tree, unlike story-list tools or search_stories which return lists without discussion context. Read-only, idempotent, and unauthenticated; the client caches GET responses in memory for 60 seconds and throttles upstream HN/Algolia requests to 10 requests/second with a burst of 20, while upstream HTTP, rate-limit, or response-shape failures are returned as tool errors. Missing root items throw a 404-style error, deleted/dead descendants are skipped, and broad branches are truncated by maxChildren; use only when you already have an item ID.
| Name | Required | Description | Default |
|---|---|---|---|
| itemId | Yes | Hacker News item ID to fetch. Must be a nonnegative integer from HN item URLs or prior tool results. | |
| depth | No | Maximum reply nesting depth to expand. Defaults to 2; valid range is 1 to 6. | |
| maxChildren | No | Maximum number of child comments fetched per item at each depth. Defaults to 20; valid range is 1 to 50. |
| Name | Required | Description |
|---|---|---|
| thread | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers traits: client caching, throttling, error handling (missing root 404, deleted/dead skipped), and truncation via maxChildren.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is efficient but dense; could be split for readability, but it packs significant information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and an output schema, the description covers error scenarios, caching, throttling, and constraints, making it fully informative for agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters (100% coverage), but the description adds behavioral context like truncation and comment tree expansion, aiding understanding beyond schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches one Hacker News item by ID and expands its comment tree, distinguishing it from sibling tools like story-list and search_stories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly contrasts with alternative tools ('unlike story-list tools or search_stories') and states when to use ('only when you already have an item ID'), along with noting read-only, idempotent, unauthenticated access.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches Hacker News newest stories from the Firebase newstories ranking and returns summaries, unlike get_top_stories which follows front-page rank or search_stories which uses keywords. Read-only, idempotent, and unauthenticated; the client caches GET responses in memory for 60 seconds and throttles upstream HN/Algolia requests to 10 requests/second with a burst of 20, while upstream HTTP, rate-limit, or response-shape failures are returned as tool errors. Use when recency matters more than score or comment activity; use get_top_stories or get_best_stories when popularity signals matter.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of stories to return. Defaults to 10; valid range is 1 to 30. |
| Name | Required | Description |
|---|---|---|
| stories | Yes | |
| returned | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description fully discloses caching (60s in-memory), rate limiting (10 req/s burst 20), and error handling (upstream failures returned as tool errors). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with front-loaded purpose and comparisons, followed by behavior details. Every sentence adds value, though it could be slightly shorter without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description covers purpose, usage, behavior, and parameters thoroughly. The only minor gap (return summaries format) is likely filled by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter (limit) that already has a description. The description adds no extra parameter info beyond what the schema provides, so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches HN newest stories from the newstories ranking and returns summaries. It explicitly distinguishes from siblings like get_top_stories (front-page rank) and search_stories (keywords).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use (recency matters more than score/comment activity) and when not (use get_top_stories or get_best_stories for popularity signals). Also notes read-only, idempotent, unauthenticated nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches the current Hacker News front-page/topstories ranking from the public Firebase API and returns story summaries, unlike search_stories keyword lookup or get_item_thread discussion expansion. Read-only, idempotent, and unauthenticated; the client caches GET responses in memory for 60 seconds and throttles upstream HN/Algolia requests to 10 requests/second with a burst of 20, while upstream HTTP, rate-limit, or response-shape failures are returned as tool errors. Use for "top", "front page", or currently popular stories; use get_new_stories for newest submissions, get_best_stories for HN best ranking, search_stories for keywords, and get_item_thread for a known item ID.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of stories to return. Defaults to 10; valid range is 1 to 30. |
| Name | Required | Description |
|---|---|---|
| stories | Yes | |
| returned | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description fully covers behavior: read-only, idempotent, unauthenticated, 60-second in-memory cache, 10 req/s throttling with burst of 20, error handling for upstream failures. No behavioral gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized and front-loaded. Every sentence adds value given the lack of annotations. Minor verbosity but not excessive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a simple single integer parameter and an output schema present, the description covers behavior, caching, throttling, error handling, and usage guidance completely for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (limit) has 100% schema coverage with default and range, so the description adds little beyond 'returns story summaries' context. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it fetches Hacker News front-page/top stories from the public Firebase API and returns summaries. Explicitly distinguishes from siblings like search_stories and get_item_thread.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says use for 'top', 'front page', or currently popular stories, and lists alternatives (get_new_stories, get_best_stories, search_stories, get_item_thread) for other use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches Hacker News stories by keyword via the public Algolia HN API and returns summaries ranked by Algolia relevance/popularity, not exact phrase matching or HN front-page order. Read-only, idempotent, and unauthenticated; the client caches GET responses in memory for 60 seconds and throttles upstream HN/Algolia requests to 10 requests/second with a burst of 20, while upstream HTTP, rate-limit, or response-shape failures are returned as tool errors. Empty queries are rejected, no-match searches return an empty stories array, and this is the right tool for topics or phrases; use story-list tools for rankings and get_item_thread for comments on a known item.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Non-empty keyword query sent verbatim to Algolia HN search; matching is Algolia token-based search, not guaranteed exact phrase matching. | |
| limit | No | Maximum number of stories to return. Defaults to 10; valid range is 1 to 30. |
| Name | Required | Description |
|---|---|---|
| stories | Yes | |
| returned | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses all relevant behavioral traits: read-only, idempotent, unauthenticated, client caching (60s), throttling (10 req/s burst 20), error handling, and behavior for empty/no-match queries. Since no annotations are provided, the description fully compensates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph but every sentence adds value. It is concise relative to the amount of information conveyed. A structured list might improve readability, but it is not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown but indicated), the description does not need to explain return values. It covers input constraints, behavior, error handling, and alternative tools, making it complete for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. The description adds value by clarifying that query is sent verbatim and matching is token-based (not exact phrase), and that limit defaults to 10 with max 30. This is useful context beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (searches by keyword), the resource (Hacker News stories via Algolia API), and the ranking method (relevance/popularity). It also distinguishes from sibling tools by noting when to use this tool versus story-list tools and get_item_thread.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (topics or phrases) and when not to (use story-list tools for rankings, get_item_thread for comments). Also covers edge cases (empty query rejected, no-match returns empty array), providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
get_best_storiesget_item_thread3 fields changedInput schema / properties / depth / descriptionAdded value: +"Maximum reply nesting depth to expand. Defaults to 2; valid range is 1 to 6."Input schema / properties / itemId / descriptionAdded value: +"Hacker News item ID to fetch. Must be a nonnegative integer from HN item URLs or prior tool results."Input schema / properties / maxChildren / descriptionAdded value: +"Maximum number of child comments fetched per item at each depth. Defaults to 20; valid range is 1 to 50."get_new_storiesget_top_stories1 field changedInput schema / properties / limit / descriptionAdded value: +"Maximum number of stories to return. Defaults to 10; valid range is 1 to 30."search_stories2 fields changedInput schema / properties / limit / descriptionAdded value: +"Maximum number of stories to return. Defaults to 10; valid range is 1 to 30."Input schema / properties / query / descriptionAdded value: +"Non-empty keyword query sent verbatim to Algolia HN search; matching is Algolia token-based search, not guaranteed exact phrase matching."v0.1.0get_item_threadget_top_storiessearch_storiesEach tool targets a distinct Hacker News resource and operation: top stories, new stories, best stories, keyword search, and item threads. Descriptions explicitly differentiate them, leaving no ambiguity.
All tool names follow a verb_noun pattern (get_best_stories, get_item_thread, get_new_stories, get_top_stories, search_stories). The pattern is consistent and predictable.
With 5 tools, the set is well-scoped for a Hacker News reader. Each tool covers a primary data retrieval need without unnecessary redundancy.
The toolkit covers the main read operations for stories (rankings, search, threads). Minor gaps like missing user or poll retrieval exist, but for a story-focused toolkit it is largely complete.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
One profile — skills, credentials, and memory — synced to every agent tool via one MCP URL.
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
AI agent registry — search, discover, register, and connect agents via MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Markgatcha/universal-mcp-toolkit'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
