MCP 服务器

mcp-counter-server

Provides stateful counter tools for AI assistants, enabling accurate counting and tracking of metrics via tag-based or direct tool calls.

README

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:

Embed counter tags directly in their output as they work
Process all tags in one call with counter_parse_and_apply
Track multiple metrics simultaneously with perfect accuracy
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.