@debugmcp/shared

Shared interfaces, types, and base classes for the MCP Debugger monorepo.

Overview

This package contains all the shared contracts and types that are used across the MCP Debugger ecosystem. By centralizing these definitions, we ensure consistency and enable better type safety across all packages.

Installation

``bash
npm install @debugmcp/shared
`

What's Included

$3

#### Debug Adapter Interfaces
- IDebugAdapter - Core interface for all debug adapter implementations
- AdapterState - Enumeration of adapter states
- AdapterCapabilities - DAP capabilities structure
- AdapterConfig - Configuration for adapter instances
- AdapterCommand - Command structure for launching adapters

#### External Dependencies
- IFileSystem - File system operations interface
- IProcessManager - Process management interface
- INetworkManager - Network operations interface
- ILogger - Logging interface
- IEnvironment - Environment information interface
- IProxyManager - Debug proxy management interface

#### Adapter Registry
- IAdapterFactory - Factory interface for creating adapters
- IAdapterRegistry - Registry for managing adapter factories
- AdapterDependencies - Dependencies required by adapters
- AdapterMetadata - Metadata about adapter implementations

$3

#### Session Types
- SessionState - Debug session states
- SessionLifecycleState - Session lifecycle states
- ExecutionState - Execution states (running, paused, etc.)
- DebugSessionInfo - Public session information
- Breakpoint - Breakpoint structure
- Variable - Variable information
- StackFrame - Stack frame information

#### Configuration Types
- GenericLaunchConfig - Base launch configuration
- LanguageSpecificLaunchConfig - Language-specific launch configs
- DebugFeature - Enumeration of debug features

$3

- AdapterFactory - Abstract base class for adapter factories

$3

- DebugLanguage - Supported debug languages (Python, Mock, etc.)
- AdapterState - Adapter lifecycle states
- SessionState - Session states
- AdapterErrorCode - Error codes for adapter operations

Usage Examples

$3

`typescript
import {
IDebugAdapter,
AdapterState,
DebugLanguage,
AdapterDependencies
} from '@debugmcp/shared';

export class MyDebugAdapter implements IDebugAdapter {
readonly language = DebugLanguage.PYTHON;
readonly name = 'My Python Adapter';

constructor(dependencies: AdapterDependencies) {
// Initialize with dependencies
}

async initialize(): Promise {
// Initialization logic
}

// ... implement other required methods
}
`

$3

`typescript
import {
AdapterFactory,
IDebugAdapter,
AdapterDependencies,
AdapterMetadata,
DebugLanguage
} from '@debugmcp/shared';

export class MyAdapterFactory extends AdapterFactory {
createAdapter(dependencies: AdapterDependencies): IDebugAdapter {
return new MyDebugAdapter(dependencies);
}

getMetadata(): AdapterMetadata {
return {
language: DebugLanguage.PYTHON,
displayName: 'Python',
version: '1.0.0',
// ... other metadata
};
}
}
`

$3

`typescript
import {
SessionState,
DebugSessionInfo,
Breakpoint
} from '@debugmcp/shared';

function handleSessionState(session: DebugSessionInfo) {
switch (session.state) {
case SessionState.RUNNING:
console.log('Session is running');
break;
case SessionState.PAUSED:
console.log('Session is paused');
break;
// ... handle other states
}
}
`

Development

$3

`bash
npm run build
`

$3

`bash
npm test
`

$3

`bash
npm run type-check
`

Architecture

This package follows a clear separation of concerns:

1. Interfaces - Define contracts that implementations must follow
2. Types - Define data structures and type aliases
3. Base Classes - Provide common functionality for implementations
4. Enumerations - Define constant values and states

Migration Guide

If you're migrating from the monolithic structure to use this shared package:

1. Update your imports:
`typescript
// Before
import { IDebugAdapter } from '../adapters/debug-adapter-interface.js';

// After
import { IDebugAdapter } from '@debugmcp/shared';
`

2. Remove local interface definitions that are now in shared
3. Update your tsconfig.json to reference the shared package
4. Ensure your package.json includes @debugmcp/shared as a dependency

Contributing

When adding new shared types or interfaces:

1. Place interfaces in src/interfaces/
2. Place types in src/models/
3. Place base classes in src/factories/
4. Update src/index.ts` to export new additions
5. Document the additions in this README
6. Add tests if applicable

License

MIT - See LICENSE file in the repository root