Agent skill

report-issue-framework

File a bug or feature request against @cyanheads/mcp-ts-core when you hit a framework issue. Use when a builder, utility, context method, or config behaves contrary to the documented API — not for server-specific application bugs.

View SKILL.md on GitHub Repository
Stars 131
Forks 24

Install this agent skill to your Project

npx add-skill https://github.com/cyanheads/mcp-ts-core/tree/main/skills/report-issue-framework

Metadata

Additional technical details for this skill

type
workflow
author
cyanheads
version
1.1
audience
external

SKILL.md

When to Use

You've isolated a problem to @cyanheads/mcp-ts-core itself — not your server code, not a misconfiguration, not a missing peer dependency. Typical triggers:

  • Framework builder (tool(), resource(), prompt()) rejects valid input or produces incorrect output
  • createApp() or createWorkerHandler() fails on a valid config
  • Context properties (ctx.log, ctx.state, ctx.elicit, etc.) behave contrary to docs
  • A utility from /utils, /errors, /auth, /storage, /services returns wrong results or throws unexpectedly
  • Type exports are incorrect or missing (compile error on documented usage)
  • The definition linter (bun run lint:mcp) produces false positives or misses real violations

Before Filing

  1. Confirm framework version — bun pm ls @cyanheads/mcp-ts-core or check node_modules/@cyanheads/mcp-ts-core/package.json
  2. Check you're on latest — bun outdated @cyanheads/mcp-ts-core. If behind, update and retest before filing.
  3. Isolate the issue — reproduce with a minimal handler or standalone script. Strip server-specific services, config, and dependencies. If the bug disappears when isolated, it's likely in your server code.
  4. Search existing issues — don't file duplicates:
bash
gh issue list -R cyanheads/mcp-ts-core --search "your error message or keyword"

Redact Before Posting

GitHub issues are public. Do not include secrets, credentials, API keys, or tokens. Redact sensitive values from env vars, headers, and logs before submitting. Replace with obvious placeholders: REDACTED, sk-...REDACTED. Do not rely on partial masking — partial keys can still be exploited.

Filing a Bug

The repo has YAML form issue templates. Use --web to open the form in the browser (preferred when available), or pass --title + --body for non-interactive use.

Browser (interactive)

bash
gh issue create -R cyanheads/mcp-ts-core --template "Bug Report" --web

CLI (non-interactive)

Structure the --body to match the template's form fields:

bash
gh issue create -R cyanheads/mcp-ts-core \
  --title "bug(scope): concise description" \
  --label "bug" \
  --body "$(cat <<'ISSUE'
### mcp-ts-core version

0.1.29

### Runtime

Bun

### Runtime version

Bun 1.2.x

### Transport

stdio

### OS

macOS 15.x

### Description

Brief explanation of the bug — what you expected vs what happened.

### Reproduction

```ts
import { tool, z } from '@cyanheads/mcp-ts-core';

export const broken = tool('broken_example', {
  description: 'Minimal repro.',
  input: z.object({ id: z.string().describe('ID') }),
  output: z.object({
    name: z.string().describe('Name'),
    extra: z.string().optional().describe('Optional field'),
  }),
  async handler(input, ctx) {
    return { name: 'test' }; // omitting optional field causes validation error
  },
});
```

### Actual behavior

```
Error: Output validation failed: ...
```

### Expected behavior

Omitting an optional output field should pass validation.

### Additional context

Any workarounds, related issues, or observations.
ISSUE
)"

Title conventions

Format: bug(<scope>): concise description

Scope When
tool Tool builder, handler, format, annotations
resource Resource builder, handler, list, params
prompt Prompt builder, generate, args
context Context, logger, state, progress, elicit, sample
config AppConfig, parseConfig, env parsing
errors McpError, error factories, auto-classification
auth Auth modes, scope checking, JWT/OAuth
storage StorageService, providers
transport stdio/http transport, SSE, session handling
worker createWorkerHandler, Worker runtime
utils Utilities (formatting, parsing, pagination, etc.)
linter Definition linter false positives/negatives
types Type exports, type inference
services LLM, Speech, Graph services
deps Dependency issues, peer dep conflicts

Labels

Label When
bug Something broken
regression Worked before, broken after update
types TypeScript type issue
docs Documentation is wrong or misleading
enhancement Feature request or improvement (not a bug)

Combine labels: --label "bug" --label "types".

Attaching logs or stack traces

For long output, write to a file and attach:

bash
bun run dev:stdio 2>&1 | head -100 > /tmp/mcp-error.log

# As part of a new issue
gh issue create -R cyanheads/mcp-ts-core \
  --title "bug(transport): stdio crashes on large payload" \
  --label "bug" \
  --body-file /tmp/mcp-error.log

# Or as a comment on an existing issue
gh issue comment <number> -R cyanheads/mcp-ts-core --body-file /tmp/mcp-error.log

Filing a Feature Request

Browser (interactive)

bash
gh issue create -R cyanheads/mcp-ts-core --template "Feature Request" --web

CLI (non-interactive)

bash
gh issue create -R cyanheads/mcp-ts-core \
  --title "feat(scope): concise description" \
  --label "enhancement" \
  --body "$(cat <<'ISSUE'
### Use case

Describe the problem you're solving and why the framework should handle it.

### Proposed API

```ts
import { withRetry } from '@cyanheads/mcp-ts-core/utils';

const result = await withRetry(() => fetchExternal(url), {
  maxAttempts: 3,
  backoff: 'exponential',
});
```

### Alternatives considered

What you tried or considered instead.
ISSUE
)"

Following Up

bash
# Check issue status
gh issue view <number> -R cyanheads/mcp-ts-core

# Add context or respond to maintainer questions
gh issue comment <number> -R cyanheads/mcp-ts-core --body "Additional context..."

# List your open issues
gh issue list -R cyanheads/mcp-ts-core --author @me

Checklist

  • Confirmed bug is in @cyanheads/mcp-ts-core, not server code
  • Running latest (or documented) framework version
  • Searched existing issues — no duplicate found
  • All secrets, credentials, and tokens redacted
  • Issue filed with: version, runtime, repro code, actual vs expected behavior

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

cyanheads/mcp-ts-core

add-resource

Scaffold a new MCP resource definition. Use when the user asks to add a resource, expose data via URI, or create a readable endpoint.

131 24
Explore
cyanheads/mcp-ts-core

field-test

Exercise tools, resources, and prompts with real-world inputs to verify behavior end-to-end. Use after adding or modifying definitions, or when the user asks to test, try out, or verify their MCP surface. Calls each definition with realistic and adversarial inputs and produces a report of issues, pain points, and recommendations.

131 24
Explore
cyanheads/mcp-ts-core

release

Verify release readiness and publish. The git wrapup protocol handles version bumps, changelog, README, commits, and tagging during the coding session. This skill verifies nothing was missed, runs final checks, and presents the irreversible publish commands.

131 24
Explore
cyanheads/mcp-ts-core

add-export

Add a new subpath export to the @cyanheads/mcp-ts-core package. Use when creating a new public API surface that consumers import from a dedicated subpath (e.g., @cyanheads/mcp-ts-core/newutil).

131 24
Explore
cyanheads/mcp-ts-core

api-errors

McpError constructor, JsonRpcErrorCode reference, and error handling patterns for `@cyanheads/mcp-ts-core`. Use when looking up error codes, understanding where errors should be thrown vs. caught, or using ErrorHandler.tryCatch in services.

131 24
Explore
cyanheads/mcp-ts-core

api-utils

API reference for all utilities exported from `@cyanheads/mcp-ts-core/utils`. Use when looking up utility method signatures, options, peer dependencies, or usage patterns.

131 24
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results