A stream parser for Claude's message API that provides real-time access to:
- Text content
- Thought processes
- Action invocations
- Error handling
npm install @anthropic-ai/mcp-stream-parser
import { AnthropicStreamParser } from '@anthropic-ai/mcp-stream-parser';
const parser = new AnthropicStreamParser({
apiKey: 'your-api-key'
});
// Listen for events
parser.on('text', event => {
console.log('Text:', event.content);
});
parser.on('thought', event => {
console.log('Thought:', event.content);
});
parser.on('action', event => {
console.log('Action:', event.name, event.params);
});
parser.on('error', event => {
console.error('Error:', event.error);
});
parser.on('typing', event => {
if (event.isTyping) {
console.log('Claude is typing...');
} else {
console.log('Claude stopped typing');
}
});
// Send a message
await parser.sendMessage({
model: 'claude-3-opus-20240229',
content: 'Hello Claude!'
});
The parser can be configured with various options:
const parser = new AnthropicStreamParser({
apiKey: 'your-api-key',
// Parser mode
mode: ParserMode.MESSAGE, // or ParserMode.STREAM
// System prompt configuration
systemPrompt: {
content: 'Your custom system prompt',
prependInstructions: true // or false
},
// Message handling
message: {
maxLength: 2000,
splitPoints: ['\n\n', '. ', ' '],
overflow: 'split' // or 'error'
},
// Buffer management
buffer: {
maxSize: 64 * 1024, // 64KB
overflow: 'error', // or 'truncate'
flushOnNewline: true
},
// Throttling configuration
throttle: {
enabled: true,
readingSpeed: 250, // words per minute
minPause: 100, // minimum pause between emissions in ms
maxBuffer: 200 // maximum characters to buffer before forcing emission
},
// Debug options
debug: {
enabled: true,
state: true,
events: true,
buffer: true,
json: true,
stream: true,
logger: console.debug
}
});
Emitted for regular text content. Text events are throttled based on the throttling configuration to provide a more natural reading experience:
interface TextEvent {
type: EventType.TEXT;
content: string;
offset: number;
blockIndex?: number;
splitInfo?: {
position: number;
reason: string;
};
}
Emitted when Claude expresses its thought process. Thought events are emitted immediately without throttling:
interface ThoughtEvent {
type: EventType.THOUGHT;
content: string;
offset: number;
blockIndex?: number;
hasAction: boolean;
}
Emitted when Claude invokes an action. Action events are emitted immediately without throttling:
interface ActionEvent {
type: EventType.ACTION;
name: string;
params: Record<string, unknown>;
offset: number;
blockIndex?: number;
thoughtContent?: string;
}
Emitted when Claude starts or stops generating content:
interface TypingEvent {
type: EventType.TYPING;
isTyping: boolean;
offset: number;
blockIndex?: number;
}
The typing event is emitted with isTyping: true
when Claude starts processing content, and isTyping: false
when it finishes processing a block or sending a message. This can be used to implement typing indicators in user interfaces.
Example usage:
parser.on('typing', event => {
if (event.isTyping) {
console.log('Claude is typing...');
// Show typing indicator
} else {
console.log('Claude stopped typing');
// Hide typing indicator
}
});
Emitted when parsing errors occur:
interface ErrorEvent {
type: EventType.ERROR;
error: Error;
fatal: boolean;
offset: number;
blockIndex?: number;
partialContent?: string;
}
The parser provides detailed error information through the error event:
parser.on('error', event => {
const { error, fatal, partialContent } = event;
if (fatal) {
console.error('Fatal error:', error);
// Handle unrecoverable error
} else {
console.warn('Non-fatal error:', error);
// Continue processing
}
if (partialContent) {
console.log('Partial content:', partialContent);
// Handle incomplete content
}
});
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add some amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
The parser includes a throttling mechanism to provide a more natural reading experience for text content. Throttling can be configured with the following options:
const parser = new AnthropicStreamParser({
apiKey: 'your-api-key',
throttle: {
enabled: true, // Enable/disable throttling
readingSpeed: 250, // Target reading speed in words per minute
minPause: 100, // Minimum pause between emissions in milliseconds
maxBuffer: 200 // Maximum characters to buffer before forcing emission
}
});
Note that thought and action events bypass the throttling mechanism and are emitted immediately to ensure responsive tool usage and thought process visibility.