feat(angular-mcp-server): add get_ds_story_data MCP tool

[Karnaukhov-kh]

Why

During migration, an AI agent needs to understand how a component is actually used, not just its TypeScript API.

The existing get_ds_component_data tool returns file paths to implementation and docs, but the agent still has to read and parse the raw .stories.ts file itself. For some components, that means working through a 28K file with 17 stories, most of which are Storybook showcase stories that are irrelevant for migration.

This tool closes that gap by parsing the story file and returning only the information the agent actually needs: selector style, input API with defaults, slots, form integration patterns, and real usage templates — at only 12–26% of the raw file size.

Template Cleaning

• Strips inline styles
• Removes HTML comments
• Removes Storybook layout wrapper divs
• Collapses templates to single-line for token efficiency
• Replaces ${args.x} interpolations with "..." placeholders
• Detects argsToTemplate(args) and marks as [all-meta-args-bound]
• Returns null for programmatically generated templates (avoids garbage output)

Output Parameters

• format: markdown (default) or json
• descriptionLength: short (default, first sentence) or full
• excludeTags:
  • default: ["docs-template"]
  • filters out showcase stories
  • reduces output size by ~40–50% for most components

Size Comparison (default filtering)

Component	Raw file	Tool output	Ratio
button	28K	3.4K	12%
checkbox	10.6K	1.3K	12%
badge	13.3K	2.3K	17%
input-field	37K	5.4K	15%
modal	13.5K	2.8K	21%
accordion	11.6K	3.1K	26%

What

This pull request introduces a new tool, get-ds-story-data, to the Angular MCP server. The tool allows AI agents and developers to extract structured information and usage patterns from Storybook .stories.ts files for Design System (DS) components. It includes both code and documentation updates, as well as supporting types and utilities to enable markdown or JSON output. The tool is integrated into the main DS tools collection and referenced in the planning workflow.

Key additions and changes:

New Tool: Story Data Extraction

• Added get-ds-story-data tool, which parses Storybook .stories.ts files for a given DS component and outputs a compact summary of its API surface, usage patterns, and story templates. The tool supports filtering by story tags, short/full descriptions, and output in markdown or JSON format.
• Introduced supporting type definitions for parsed story data, including selector info, arg types, slots, form integration, and story entries, in models/types.ts.
• Added a utility to format parsed story data as concise markdown, optimizing for readability and token efficiency.

Integration

• Registered the new tool in the DS tools export and included it in the main tools collection for use by the server. [1] [2]
• Exported the tool from the story parser index for modular usage.

Documentation

• Updated docs/tools.md to document the new tool's purpose, parameters, and best practices, and to include it in the recommended planning workflow for AI agents. [1] [2]

[Copilot]

Pull request overview

Adds a new get-ds-story-data tool to the Angular MCP server to extract structured, token-efficient usage information from Storybook .stories.ts files (selector style, inputs/argTypes, slots, form bindings, and cleaned templates), with supporting shared parsing utilities and documentation updates.

Changes:

• Introduces get-ds-story-data tool + story parsing/markdown formatting utilities and tests.
• Adds shared low-level helpers (escapeRegex, source-text extraction utilities) and wires them into existing DS utilities.
• Updates tooling documentation and recommended planning workflow to include the new tool.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/shared/utils/src/lib/regex.utils.ts	Adds shared escapeRegex helper for safe dynamic regex building.
packages/shared/utils/src/index.ts	Exports the new regex utility from @push-based/utils.
packages/shared/typescript-ast-utils/src/lib/source-text.utils.ts	Adds source-text extractors for template literals and balanced blocks.
packages/shared/typescript-ast-utils/src/index.ts	Exposes the new source-text helpers via package exports.
packages/angular-mcp-server/src/lib/tools/ds/tools.ts	Registers the new DS story tool in the MCP server tool set.
packages/angular-mcp-server/src/lib/tools/ds/story-parser/utils/story-parser.utils.ts	Implements story parsing (AST-first + regex helpers) and data extraction.
packages/angular-mcp-server/src/lib/tools/ds/story-parser/utils/story-markdown-formatter.utils.ts	Adds compact markdown formatting for parsed story data.
packages/angular-mcp-server/src/lib/tools/ds/story-parser/utils/tests/story-parser.utils.spec.ts	Adds unit tests for parsing/cleaning/selector/form detection.
packages/angular-mcp-server/src/lib/tools/ds/story-parser/models/types.ts	Defines structured output types for the new tool.
packages/angular-mcp-server/src/lib/tools/ds/story-parser/index.ts	Exports the new tool module entrypoint.
packages/angular-mcp-server/src/lib/tools/ds/story-parser/get-ds-story-data.tool.ts	Implements the MCP tool schema + handler (file resolution, filtering, formatting).
packages/angular-mcp-server/src/lib/tools/ds/shared/utils/template-helpers.ts	Adds template cleaning and selector/form/slot detection helpers.
packages/angular-mcp-server/src/lib/tools/ds/shared/utils/regex-helpers.ts	Reuses shared escapeRegex instead of local duplication.
packages/angular-mcp-server/src/lib/tools/ds/project/utils/styles-report-helpers.ts	Reuses shared escapeRegex instead of local duplication.
docs/tools.md	Documents get-ds-story-data and inserts it into the recommended workflow.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.