Counter MCP Server

A Model Context Protocol (MCP) server that provides stateful counter tools for AI assistants. This solves the problem of AI's inability to reliably count items during iteration by providing explicit, accurate counter tools.

The Problem

AI language models use probabilistic pattern matching rather than actual counting. This makes them unreliable for tasks like:

• Tracking how many files have been processed
• Counting iterations in a loop
• Maintaining progress through multi-step tasks
• Accurately tallying errors, warnings, or other metrics

The Solution

This MCP server provides explicit counter tools that maintain accurate state. AI assistants can:

1. Embed counter tags directly in their output as they work
2. Process all tags in one call with counter_parse_and_apply
3. Track multiple metrics simultaneously with perfect accuracy
4. Review history to see every operation performed

Quick Start

Installation

git clone https://github.com/Discordit142/mcp-counter-server.git
cd mcp-counter-server
npm install
npm run build

Add to VS Code

Add this to your VS Code User Settings (Ctrl+, → search "MCP" → Edit in settings.json):

{
  "mcp.servers": {
    "counter": {
      "type": "stdio",
      "command": "node",
      "args": ["<path-to-repo>/dist/index.js"]
    }
  }
}

Replace <path-to-repo> with the actual path to your cloned repository.

Usage

Method 1: Tag-Based Counting (Recommended)

Embed counter tags directly in your text as you work, then process them all at once:

Processing files in workspace...

Analyzing src/index.ts [+1:files_analyzed]
- Found 15 async functions [+15:async_functions]
- Found 2 interface definitions [+2:interfaces]
- Detected 3 minor issues [+3:warnings]

Analyzing package.json [+1:files_analyzed]
- Configuration validated

Analyzing README.md [+1:files_analyzed]
- Documentation complete

Analysis finished!

Then call counter_parse_and_apply with the entire text above, and get:

{
  "counters": {
    "files_analyzed": 3,
    "async_functions": 15,
    "interfaces": 2,
    "warnings": 3
  },
  "errors": []
}

Tag Syntax

Shorthand (explicit numbers required):

• [+N:counter_id] - Increment by N
• [-N:counter_id] - Decrement by N
• [reset:counter_id] - Reset to 0
• [delete:counter_id] - Delete counter
• [set:N:counter_id] - Set to specific value

Full Syntax (alternative):

• [-counter:counter_id:+N-] or [-c:counter_id:+N-] - Increment/decrement
• [-counter:counter_id:reset-] - Reset
• [-counter:counter_id:delete-] - Delete
• [-counter:counter_id:set:N-] - Set value

Examples:

[+1:files]              → files: 1
[+15:lines_of_code]     → lines_of_code: 15
[-3:errors]             → errors: -3
[reset:temp]            → temp: 0
[set:100:progress]      → progress: 100
[delete:old_counter]    → (counter removed)

Method 2: Direct Tool Calls

For simple cases, call counter tools directly:

counter_increment(counter_id: "files_processed")
counter_increment(counter_id: "errors_found", amount: 5)
counter_get(counter_id: "files_processed")  // Returns current value
counter_reset(counter_id: "errors_found")   // Reset to 0
counter_delete(counter_id: "temp_counter")  // Remove completely

Available Tools

counter_parse_and_apply

Parse counter tags from text and execute all operations in order.

Arguments:

• text (required): Text containing counter tags
• debug (optional): Enable debug mode for detailed results (default: false)

Streamlined Mode (default):

{
  "counters": { "files": 5, "errors": 2 },
  "errors": []
}

Debug Mode:

{
  "counters": { "files": 5 },
  "errors": [],
  "processed_tags": [
    { "tag": "[+1:files]", "result": "files incremented by 1" },
    { "tag": "[+4:files]", "result": "files incremented by 4" }
  ]
}

counter_increment

Increment a counter by a specified amount (creates if doesn't exist).

Arguments:

• counter_id (required): Unique identifier
• amount (optional): Amount to increment (default: 1, can be negative)

counter_get

Get current value and metadata for a counter.

Arguments:

• counter_id (required): Counter to retrieve

counter_reset

Reset a counter to 0 (preserves history).

Arguments:

• counter_id (required): Counter to reset

counter_list

List all active counters with their current values.

counter_history

Get operation history for a counter.

Arguments:

• counter_id (required): Counter to retrieve history for
• limit (optional): Max number of recent entries

counter_delete

Permanently delete a counter and its history.

Arguments:

• counter_id (required): Counter to delete

Real-World Example

Starting database migration...

Connecting to database... [+1:steps_completed]
Backing up existing data... [+1:steps_completed]

Processing 1000 records:
Record batch 1-100: [+100:records_processed] [+2:errors_found]
Record batch 101-200: [+100:records_processed] [+1:errors_found]
Record batch 201-1000: [+800:records_processed]

Migration complete!
Setting total records: [set:1000:total_records]

Final status:
- Steps completed: (will show 2)
- Records processed: (will show 1000)
- Errors found: (will show 3)

Pass this text to counter_parse_and_apply and get accurate counts instantly.

Features

✅ Accurate counting - No probabilistic approximation
✅ Batch processing - Process hundreds of tags in one call
✅ History tracking - Every operation logged with timestamp
✅ Multiple counters - Track different metrics simultaneously
✅ Persistent within session - Counters survive across tool calls
✅ Flexible operations - Increment, decrement, set, reset, delete
✅ Error handling - Continues processing even if individual tags fail
✅ Race-condition safe - Per-counter locking prevents conflicts

Development

npm run build   # Compile TypeScript
npm run watch   # Watch mode for development
npm run dev     # Run with Node inspector
npm start       # Run the compiled server

Architecture

• CounterStore: In-memory store with per-counter locking
• Counter: Data structure with id, value, history, timestamps
• parseAndApplyTags: Regex-based tag extraction and processing
• MCP Server: Exposes tools via Model Context Protocol

Use Cases

• Multi-file analysis (track files, functions, classes found)
• Long-running operations (track progress, errors, warnings)
• Batch processing (accurately count processed items)
• Quality metrics (track code quality scores across multiple files)
• Agent workflows (multiple agents incrementing shared counters)
• Preserving calculations past context compression: Store important calculation results as named counters (e.g., [set:15:error_rate_percentage]) to survive conversation summarization. AI assistants can retrieve these values later even after context is compressed.

License

MIT License - see LICENSE file for details

Contributing

Issues and pull requests welcome at github.com/Discordit142/mcp-counter-server