Skip to main content
Glama
malkreide

hn-tech-signal-mcp

by malkreide
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

🇨🇭 Part of the Swiss Public Data MCP Portfolio

📡 hn-tech-signal-mcp

Version License: MIT Python 3.11+ MCP No Auth Required CI

MCP server for global tech & AI signal intelligence — aggregates HackerNews, arXiv, Lobste.rs and GitHub into a structured briefing. No API key required.

🇩🇪 Deutsche Version

Demo

Demo: Claude using tech_signal_digest across arXiv, HackerNews and GitHub

Overview

hn-tech-signal-mcp turns any AI assistant into a proactive tech intelligence analyst. The server aggregates four signal layers — research frontier, developer discourse, curated signal, and open-source practice — into a single, structured briefing.

No authentication required. All four data sources are public APIs. Optional: set GITHUB_TOKEN for higher GitHub rate limits (5,000 req/h vs. 60 req/h unauthenticated).

Anchor demo query: "Give me a tech signal digest on AI today — what is happening in research, developer discourse and open source?"

Related MCP server: harness-feed-mcp

Signal Architecture

FRONTIER    arXiv API      → Latest AI/ML papers (cs.AI, cs.LG, cs.CL, cs.CV)
DISCOURSE   HackerNews     → Six feeds + Algolia search + comment threads
            Lobste.rs      → Curated, lower-noise tech signal
PRACTICE    GitHub Search  → What engineers are actually building right now
            HN Show HN     → What individuals are shipping this week

Think of the four layers as a radar: arXiv shows what's coming over the horizon, HN and Lobste.rs show what practitioners are discussing, and GitHub shows what teams are actually shipping.

Within the discourse layer there are two levels of depth. The feeds and the search tell you what is being discussed; hn_discussion tells you what is actually being argued — the counter-arguments and the "we tried this in production" replies that carry the real signal.

Features

  • 🔬 Research frontier – Latest arXiv papers by category (cs.AI, cs.LG, cs.CL, and more)

  • 🔍 arXiv full-text search – Find papers by keyword, title, or author

  • 🗣️ HackerNews feeds – top, best, new, Ask HN, Show HN and YC job posts

  • 🔎 HackerNews search – Full history via Algolia, with date range filter

  • 💬 HackerNews comment threads – Read the actual discussion under a story, nested, with a bounded fetch budget

  • 🔧 Lobste.rs hottest – Curated developer signal, filterable by tag

  • 🛠️ GitHub trending AI repos – Search by topic, stars, sort by activity or popularity

  • 📋 Tech signal digest – One-call cross-source briefing in Markdown

  • ☁️ Dual transport – stdio for Claude Desktop, Streamable HTTP for cloud deployment

#

Tool

Source

Description

1

hn_top_stories

HackerNews

Six feeds: top/best/new/ask/show/job, with score filter

2

hn_search

HN Algolia

Full-text search across all HN history

3

hn_discussion

HackerNews

Nested comment thread under a story

4

arxiv_latest

arXiv

Latest papers by category (cs.AI etc.)

5

arxiv_search

arXiv

Search papers by keyword/title/author

6

lobsters_hot

Lobste.rs

Curated tech stories, filterable by tag

7

github_trending_ai

GitHub

Trending AI repos by topic and stars

8

tech_signal_digest

All sources

Aggregated Markdown briefing

HackerNews feeds

Feed

Content

Upstream size

top

Front page as ranked right now

500 items

best

Highest-voted recent stories

200 items

new

Newest submissions, unfiltered

500 items

ask

Ask HN — what practitioners are stuck on

~30 items

show

Show HN — what people are shipping

200 items

job

YC portfolio job posts (type: "job", no comments, score always 1)

~30 items

ask and job are short feeds upstream, so a large limit may return fewer stories than requested.

Prerequisites

  • Python 3.11+

  • uv or pip

  • No API key required

  • Optional: GITHUB_TOKEN for higher GitHub rate limits

Installation

# Recommended: uvx (no install step needed)
uvx hn-tech-signal-mcp

# Alternative: pip
pip install hn-tech-signal-mcp

Quickstart

# Start the server (stdio mode for Claude Desktop)
uvx hn-tech-signal-mcp

# With optional GitHub token for higher rate limits
GITHUB_TOKEN=ghp_yourtoken uvx hn-tech-signal-mcp

Try immediately in Claude Desktop:

"Give me a tech signal digest on AI today" "What are the latest cs.AI papers from the last 48 hours?" "What is HackerNews discussing about MCP this week?" "Show me trending GitHub repos for the topic 'ai-agents'"

Configuration

Environment Variables

Variable

Default

Description

GITHUB_TOKEN

–

Optional. GitHub personal access token. Without it: 60 req/h. With it: 5,000 req/h. The token is only sent to api.github.com, never to other upstreams.

MCP_TRANSPORT

stdio

Transport: stdio or streamable_http

MCP_HOST

127.0.0.1

Bind host for HTTP transport. Non-loopback values require MCP_BEARER_TOKEN.

MCP_PORT

8000

Port for HTTP transport

MCP_BEARER_TOKEN

–

Required when MCP_HOST is not loopback. Shared secret to gate the HTTP endpoint.

Claude Desktop Configuration

{
  "mcpServers": {
    "hn-tech-signal": {
      "command": "uvx",
      "args": ["hn-tech-signal-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_yourtoken_optional"
      }
    }
  }
}

Config file locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

After restarting Claude Desktop, all 7 tools are available.

Cloud Deployment (Streamable HTTP)

For use via claude.ai in the browser (e.g. on managed workstations):

Render.com (recommended):

  1. Push/fork the repository to GitHub

  2. On render.com: New Web Service → connect GitHub repo

  3. Optionally set GITHUB_TOKEN in the Render dashboard

  4. In claude.ai under Settings → MCP Servers, add: https://your-app.onrender.com/mcp

# Local HTTP mode (binds 127.0.0.1 by default)
MCP_TRANSPORT=streamable_http MCP_PORT=8000 python -m hn_tech_signal_mcp.server

# Public bind (requires bearer token, intended behind a reverse proxy that terminates TLS)
MCP_TRANSPORT=streamable_http \
MCP_HOST=0.0.0.0 \
MCP_BEARER_TOKEN="$(openssl rand -hex 32)" \
python -m hn_tech_signal_mcp.server

Hardening: the server refuses to bind to non-loopback hosts unless MCP_BEARER_TOKEN is set. Run cloud deployments behind a TLS-terminating reverse proxy (Render, Fly, Caddy, …) and treat MCP_BEARER_TOKEN as the shared client secret your proxy enforces.

Architecture

┌─────────────────┐    ┌─────────────────────────────────┐    ┌───────────────────────┐
│  Claude / AI    │────▶│   HN Tech Signal MCP             │────▶│  HackerNews Firebase  │
│  (MCP Host)     │◀────│   (MCP Server)                   │────▶│  HN Algolia Search    │
└─────────────────┘    │                                   │────▶│  arXiv.org (Atom API) │
                       │  8 Tools                          │────▶│  Lobste.rs JSON API   │
                       │  Stdio | Streamable HTTP          │────▶│  GitHub Search API    │
                       └─────────────────────────────────┘    └───────────────────────┘

Architecture decision

This server uses Architecture A (live API only, two paths per source). There is no bulk dump to fall back on.

Rationale (verified live on 2026-07-28 against the official HackerNews API):

  • All six feed endpoints ({top,best,new,ask,show,job}stories.json) answer HTTP 200 with 29–500 IDs. No auth, no rate-limit headers, Cache-Control: no-cache.

  • HackerNews publishes no bulk export, so caching is entirely this server's responsibility. TTLs live in CACHE_TTL.

  • The Firebase API has no search. Historical and full-text queries go through the Algolia index instead — that is the second path, used by hn_search.

  • item/<id>.json is one request per item. Feeds and comment threads therefore fan out, which is why both are bounded (HN_MAX_CONCURRENCY, max_comments).

Consequences:

  • Every upstream call retries with exponential backoff (2s / 4s / 8s) on network errors, 5xx and 429. Other 4xx fail fast.

  • One process-wide pooled httpx.AsyncClient, closed via the FastMCP lifespan.

  • Unknown item IDs return HTTP 200 with a null body rather than a 404 — hn_discussion translates that into an explicit "no item found" message.

Project Structure

hn-tech-signal-mcp/
├── src/
│   └── hn_tech_signal_mcp/
│       ├── __init__.py
│       └── server.py          # All 8 tools
├── tests/
│   ├── __init__.py
│   └── test_server.py         # 64 unit + 12 live tests
├── pyproject.toml
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md                  # This file (English)
└── README.de.md               # German version

MCP Protocol Version

This server speaks two protocol eras over the same endpoint. The client's first request on a connection decides which one applies; a later claim from the other era is refused.

Era

Revision

Who reaches it

initialize handshake

2024-11-05 … 2025-11-25

What today's clients speak. The server answers with the revision asked for, or with the 2025-11-25 ceiling when the request asks for something newer.

Per-request envelope

2026-07-28

A request carrying the 2026-07-28 _meta envelope opens a modern connection.

Both revisions are pinned in tests/test_protocol_version.py and asserted against the installed SDK, so a Dependabot bump of mcp cannot move either one silently. This server builds no ASGI app to send an initialize through, so the gate asserts the SDK constants rather than a measured response — the weaker form, named rather than left unsaid.

Note that the SDK's LATEST_PROTOCOL_VERSION is an alias for the modern era, not for the handshake era — pinning against it alone would leave the era that current clients actually negotiate free to drift.

Update policy. When the gate fails, do not edit the constant blindly: read the spec changelog between the two revisions, verify the server still behaves, then move the constant, this section, README.de.md and CHANGELOG.md together.

Testing

# Unit tests (no network required)
PYTHONPATH=src pytest tests/ -m "not live"

# Live integration tests (requires network)
PYTHONPATH=src pytest tests/ -m "live"

Example Use Cases

KI-Fachgruppe / AI Working Group

"Give me a tech signal digest on AI today"
→ tech_signal_digest(focus="AI")

"What are the top 5 arXiv papers on LLM agents this week?"
→ arxiv_search(query="LLM agents", category_filter="cs.AI", limit=5)

"What is HackerNews discussing about model context protocol?"
→ hn_search(query="model context protocol", days_back=30)

Research Monitoring

"Show me the latest NLP papers from arXiv"
→ arxiv_latest(category="cs.CL", limit=10)

"Search arXiv for papers on retrieval-augmented generation"
→ arxiv_search(query="retrieval augmented generation RAG", limit=10)

Open Source Intelligence

"What AI agent frameworks are trending on GitHub?"
→ github_trending_ai(topic="ai-agents", sort="updated", limit=10)

"Show me the most starred MCP-related repos"
→ github_trending_ai(topic="mcp", sort="stars", min_stars=50)

[→ More use cases by audience →](EXAMPLES.md)

arXiv Category Reference

Category

Full Name

Key Topics

cs.AI

Artificial Intelligence

Agents, planning, knowledge representation

cs.LG

Machine Learning

Training, optimisation, generalisation

cs.CL

Computation & Language

NLP, LLMs, translation, summarisation

cs.CV

Computer Vision

Image recognition, generation, multimodal

cs.RO

Robotics

Embodied AI, navigation

stat.ML

Statistics ML

Probabilistic methods, Bayesian ML

Rate Limits

Source

Auth Required

Limit

HackerNews Firebase

No

Very generous (Firebase)

HN Algolia Search

No

~10,000 req/hour

arXiv

No

~3 req/second (be respectful)

Lobste.rs

No

Reasonable use

GitHub Search

No

60 req/hour

GitHub Search

GITHUB_TOKEN

5,000 req/hour

Known Limitations

  • GitHub rate limit: 60 req/h without token. Set GITHUB_TOKEN for production use.

  • arXiv: Papers may take up to 24h to appear after submission. Weekends/holidays have delayed batches.

  • HackerNews: Top/best story lists update every few minutes. Very new stories may have low scores.

  • HackerNews ask / job feeds: Only ~30 items exist upstream, so a large limit returns fewer stories than requested. Job posts carry type: "job", no comment count, and a score of 1.

  • hn_discussion is always a sample, never the full thread: one request per comment upstream means popular stories (900+ comments) cannot be fetched whole. The budget is split across nesting levels and spread round-robin across sibling threads, so you get a representative cross-section rather than one exhaustively-read sub-thread. Check the truncated flag.

  • hn_discussion comment text is plain text, not HTML: HN's markup is stripped for readability. Do not re-render the output as HTML — the conversion is not a sanitiser.

  • Lobste.rs: Smaller community than HN; tech-focused but may not cover all AI topics.

  • tech_signal_digest: Makes ~4 concurrent requests; if one source is slow it may delay the full response.

Synergies with Other MCP Servers

hn-tech-signal-mcp combines well with:

Combination

Use Case

+ news-monitor-mcp

Global research + Swiss institutional media coverage

+ fedlex-mcp

Tech discourse + Swiss regulatory context

+ global-education-mcp

AI research trends + education policy data

+ swiss-statistics-mcp

Tech landscape + Swiss economic/structural data

Safety & Limits

  • Read-only: All tools perform HTTP GET requests only — no posts, comments, votes, or writes are issued upstream.

  • No personal data: The server queries public tech aggregators. No PII is collected; author handles in public posts/papers are returned as-is from upstream and never enriched or cross-referenced.

  • Rate limits: See the Rate Limits table. arXiv's ≤3 req/sec guidance is respected by default; GitHub search is capped at 60 req/h without a GITHUB_TOKEN. A request timeout is enforced per call.

  • No bulk harvesting: This server is built for interactive, conversational use — not for scraping or mirroring. Do not use it to bypass upstream pagination or ToS limits.

  • Terms of service: Data is subject to the ToS of each source — HackerNews, arXiv API, Lobste.rs, GitHub.

  • No guarantees: Community project, not affiliated with HackerNews / Y Combinator, arXiv / Cornell, Lobste.rs, or GitHub. Availability depends on upstream APIs.

Changelog

See CHANGELOG.md

Contributing

See CONTRIBUTING.md (Deutsch).

Security

See SECURITY.md (Deutsch) for the security posture and how to report a vulnerability.

License

MIT License — see LICENSE

Author

Hayal Oezkan · malkreide

Credits & Related Projects

Installation

Run via uv's uvx — no clone or manual install needed. Add to your MCP client config (mcpServers for Claude Desktop, Cursor and Windsurf; use a top-level servers key for VS Code in .vscode/mcp.json):

{
  "mcpServers": {
    "hn-tech-signal-mcp": {
      "command": "uvx",
      "args": [
        "hn-tech-signal-mcp"
      ]
    }
  }
}

Available Tools

8 tools
arxiv_latestA
Read-onlyIdempotent

Fetch the most recently submitted papers from arXiv AI/ML categories.

Papers appear hours before press coverage — the fastest signal of what is happening at the AI research frontier.

Categories: cs.AI (Artificial Intelligence), cs.LG (Machine Learning), cs.CL (NLP), cs.CV (Computer Vision), cs.NE (Neural Computing), stat.ML.

Args: params (ArxivLatestInput): - categories (List[str]): arXiv category codes - limit (int): Papers per category (1–20)

Returns: str: JSON with categories, total_papers, by_category dict. Each paper: id, title, abstract (400 chars), authors, published, url, pdf.

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint. The description adds that papers appear before press coverage and lists categories, but does not discuss rate limits or auth needs, which is acceptable given annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with an intro, context, category list, and Args/Returns sections. Slightly verbose but clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, the description still details return structure. It covers purpose, categories, parameters, and return format completely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides descriptions for parameters. The description's Args section repeats this info with no added meaning. Baseline 3 applies as schema coverage is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches the most recently submitted papers from arXiv AI/ML categories, specifying the resource and action. It lists the exact categories, distinguishing it from sibling tools like arxiv_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context for use ('Papers appear hours before press coverage'), implying it's for early access. However, it does not explicitly state when not to use or contrast with alternatives like arxiv_search.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hn_discussionA
Read-onlyIdempotent

Read the comment thread under a HackerNews story.

Where hn_top_stories and hn_search tell you what is being discussed, this tells you what is actually being argued — the counter-arguments, the practitioner caveats, the "we tried this in production" replies that carry the real signal. Algolia can search comment text but does not return thread structure, so this is the only way to see who replied to whom.

Get a story_id from hn_top_stories or hn_search first.

Comments are walked breadth-first, so the highest-ranked top-level comments come back first. Deleted and flagged comments are skipped. Popular threads run to several hundred comments and each one costs a request upstream, so both depth and total count are capped — check the 'truncated' flag to see whether the thread was cut short.

Args: params (HnDiscussionInput): - story_id (int): HackerNews item ID - max_depth (int): Reply nesting levels (1–4, default 2) - max_comments (int): Total comment budget (1–100, default 25) - text_chars (int): Per-comment text truncation (100–2000)

Returns: str: JSON with story{}, total_comments (as reported by HN), fetched_comments, truncated, comments[]. Each comment: id, by, posted, text, reply_count, replies[] (same shape, nested).

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (readOnly, idempotent), description details breadth-first walking, skipped comments, capping with truncated flag, and per-request cost.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with purpose, rationale, usage, behavior, and parameter list; every sentence is substantive and no waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers output format, truncated flag, and capping logic; with output schema present, description provides sufficient context for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Description lists all parameters with types and ranges, but essentially duplicates the input schema descriptions; adds no new meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specifically states it reads HN comment thread structure, and distinguishes from siblings hn_top_stories (what's discussed) and hn_search (Algolia search without thread structure).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to get a story_id from hn_top_stories or hn_search first, and explains when this tool is the only way to see thread structure versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hn_top_storiesA
Read-onlyIdempotent

Fetch stories from any of the six HackerNews front-page feeds.

Feeds: 'top' (frontpage), 'best' (highest voted), 'new' (latest), 'ask' (Ask HN — questions to the community), 'show' (Show HN — projects people are shipping), 'job' (YC company job posts).

'show' is the strongest signal for what practitioners are actually building; 'ask' for what they are stuck on. Upstream, 'ask' and 'job' hold only ~30 items, so a large limit may return fewer results.

Args: params (HnTopStoriesInput): - feed (str): 'top', 'best', 'new', 'ask', 'show', or 'job' - limit (int): Stories to return (1–30) - min_score (int): Minimum score filter (job posts score 1)

Returns: str: JSON with feed, count, stories[]. Each story: id, type, title, url, score, comments, by, posted, hn_link.

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint, idempotentHint, and destructiveHint false, which align with the read-only fetch. The description adds behavioral details like upstream feed length limits for 'ask' and 'job', and the return format including JSON structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is well-structured: purpose sentence, feed list with context, then parameter args, then return format. It is front-loaded with the core action and avoids redundancy, earning its sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existence of an output schema and annotations, the description fully explains the tool's behavior, parameters, feed semantics, and return structure, leaving no gaps for agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% (despite schema having descriptions), so the description must compensate. It explains each parameter (feed, limit, min_score) with context, including the cut-off note for 'ask' and 'job', adding value beyond the schema's own descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it fetches stories from six HackerNews front-page feeds, lists each feed with a brief definition, and distinguishes from sibling tools like hn_search and hn_discussion by focusing on feed-based retrieval rather than search or discussion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context for when to use each feed (e.g., 'show' for practitioner projects, 'ask' for stuck issues) and notes that 'ask' and 'job' feeds are short. It does not explicitly exclude cases, but the sibling list and feed descriptions imply appropriate use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lobsters_hotA
Read-onlyIdempotent

Fetch the hottest stories from Lobste.rs, a curated tech community.

Lobste.rs is smaller and more technically focused than HackerNews. Invitation-only membership ensures higher signal-to-noise ratio.

Args: params (LobstersHotInput): - limit (int): Stories to return (1–25) - tag_filter (Optional[str]): Tag substring filter (e.g. 'ai', 'ml')

Returns: str: JSON with count, stories[]. Each story: title, url, score, comments, tags, submitter, submitted_at, lobsters_url.

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds background about the community but no new behavioral traits (like rate limits or caching). There is 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by two sentences of context, and then a clear parameter list. Every sentence is informative and there is no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description fully explains what the tool does, its parameters, and the structure of its return value (including fields like title, url, score, etc.). Since an output schema exists, the return value details are sufficient. No gaps remain for this simple read-only tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters (limit and tag_filter) have descriptions in the input schema. The description repeats these details without adding new meaning. With high schema description coverage, the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches 'the hottest stories from Lobste.rs', a specific resource. It also provides context that Lobste.rs is smaller and more technically focused than HackerNews, which helps distinguish it from related tools like hn_top_stories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives context by comparing Lobste.rs to HackerNews ('smaller and more technically focused'), implying when this tool might be preferred. However, it does not explicitly state when not to use it or name sibling alternatives directly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tech_signal_digestA
Read-onlyIdempotent

Aggregate tech & AI signals from all four sources in one call.

The primary tool for a comprehensive daily or weekly tech intelligence briefing. Combines HackerNews, arXiv, Lobste.rs and GitHub into one structured JSON digest. Use 'focus' to filter for a specific topic.

Args: params (TechSignalDigestInput): - focus (Optional[str]): Topic filter (e.g. 'MCP', 'agents') - hn_limit (int): HN stories (1–10) - arxiv_limit (int): arXiv papers (1–10) - lobsters_limit (int): Lobste.rs stories (1–10) - github_limit (int): GitHub repos (1–10)

Returns: str: JSON digest with generated_at, focus, sources{hn, arxiv, lobsters, github}. Each source has label, count, and its items list.

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds that it combines sources and returns a structured JSON digest, enhancing transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is concise, front-loaded with main purpose, and well-structured with clear Args and Returns sections.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and existing annotations/output schema, the description is complete enough to guide an agent in using the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions cover all parameters fully. Description repeats parameter info without adding novel semantics beyond what schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it aggregates tech signals from four sources into one digest, distinguishing it from sibling tools that focus on individual sources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Describes itself as the primary tool for daily/weekly briefings, implying use for broad overviews. Could explicitly mention when not to use, but sibling tool list provides context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.3.0
    • Addedhn_discussion
    • Changedhn_top_stories2 fields changed
      • changedInput schema / $defs / HnTopStoriesInput / properties / feed / description
        Previous value: -"Feed type: 'top' (frontpage), 'best' (highest voted), 'new' (latest)"New value: +"Feed type: 'top' (frontpage), 'best' (highest voted), 'new' (latest), 'ask' (Ask HN questions), 'show' (Show HN projects), 'job' (YC job posts). Note: 'ask' and 'job' are short feeds (~30 items upstream)."
      • changedInput schema / $defs / HnTopStoriesInput / properties / feed / pattern
        Previous value: -"^(top|best|new)$"New value: +"^(top|best|new|ask|show|job)$"
  2. 7 tool updatesv0.2.4
    • First observedarxiv_latest
    • First observedarxiv_search
    • First observedgithub_trending_ai
    • First observedhn_search
    • First observedhn_top_stories
    • First observedlobsters_hot
    • First observedtech_signal_digest
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 8 tools

Disambiguation5/5

Each tool targets a distinct source and operation: HN has separate tools for top stories, search, and discussion; arXiv has latest and search; Lobste.rs and GitHub each have one tool, and the digest aggregates all. No overlaps.

Naming Consistency5/5

All tools follow a consistent `source_operation` pattern with lowercase and underscores (hn_top_stories, arxiv_latest, lobsters_hot, etc.), making them predictable and easy to navigate.

Tool Count5/5

8 tools is well-scoped for a multi-source tech signal aggregator. Each source gets essential operations, and the digest tool integrates them, avoiding bloat or under-provisioning.

Completeness5/5

The tool set covers the core signal retrieval needs for each source: listing, searching, and detail extraction (comments, abstracts). The digest tool ties it together, leaving no obvious gaps for the stated purpose.

Maintenance

ActivityActive
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers