skills.rest
Arasz
AraszCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

mcp-index

Indexes MCP server tools with tags and intents to recommend relevant tools per prompt.

2|Updated Jul 18, 2026
Search Tags:#cli#mcp#tagging#bm25#tool recommendation#prompt compression#tool indexing
One-click install
npx skills add https://github.com/Arasz/ai-badger --skill mcp-index-arasz
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: mcp-index
Source: https://github.com/Arasz/ai-badger/tree/main/features/common/skills/mcp-index
Command: npx skills add https://github.com/Arasz/ai-badger --skill mcp-index-arasz

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pyyaml, and includes scripts (resource) and references (resource) components.

What problem does it solve? MCP servers expose dozens of tools whose definitions bloat the system prompt and cause agents to pick the wrong tool. This Skill maintains a machine-readable index (.ai-badger/mcp-tools.json) mapping every MCP tool to tags and intent descriptions, feeding a hook that injects only relevant tool recommendations into each LLM turn. ## Core Features & Use Cases - Index lifecycle commands: init, update, validate, tag, intent, list, and migrate commands manage the JSON index, preserving manually curated tags across updates. - Multi-source server discovery: Queries hermes and claude CLIs in a fallback chain, with optional --discover per-server enumeration and catalog-based seeding for servers the host cannot enumerate. - Hook-driven recommendations: A UserPromptSubmit hook ranks indexed tools via BM25 against each prompt and injects top matches as additional context. - Use Case: After adding a new MCP server, run mcp-index update so its tools are tagged, described, and recommended on relevant prompts instead of bloating every turn. ## Quick Start Ask the agent to run mcp-index init against your project root to build the MCP tool index, then curate any tools left tagged as general.

Frequently Asked Questions about mcp-index

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I index MCP server tools for an AI agent?▼

Run mcp-index init with --target pointing at your project root. It queries the hermes or claude CLI for servers, tags each tool from the catalog or name heuristics, and writes .ai-badger/mcp-tools.json.

How do I reduce MCP tool definitions bloating the prompt?▼

Maintain an mcp-tools.json index with tags and intents per tool. The UserPromptSubmit hook then BM25-ranks indexed tools against each prompt and injects only the top matches as context instead of all definitions.

Does mcp-index work with both hermes and claude CLIs?▼

Yes, it tries hermes mcp list --json, claude mcp list, and hermes mcp list in order, taking the first listing that names a server. Pass --host to restrict to one CLI, or --from-json to read a saved listing.

Why are tools tagged as general after running init?▼

Auto-tagging heuristics cover only about 60% of tools, so unmatched ones get the general tag. Curate them with mcp-index tag, or add a tools.json entry to the framework's MCP catalog for reuse across projects.

What happens to manual tags when the index is updated?▼

Manual tags and intents are preserved: entries curated via tag or intent are marked origin manual and never overwritten. Catalog-described tools are refreshed, and vanished tools are marked removed rather than deleted.

Related Skills

Explore More Software Engineering Skills→
evolution-foundationevolution-foundation
520

dev-mcp-setup

Configure MCP servers in Claude settings.json and validate mcp__<server>__* tool discovery.

Official
Intermediate
AraszArasz
2

mcp-index

Indexes MCP server tools with tags and intents to recommend relevant tools per prompt.

Community
Advanced
AraszArasz
2

mcp-tool-indexing

Rebuilds the MCP tool index from live session tool catalogs after server reloads.

Community
Intermediate
cbrostromcbrostrom

tool-restraint

Restricts agent tool and MCP server exposure to reduce failure modes and context overhead.

Community
Basic