mcp-bbs MCP Server

bbsbot

FastMCP-based telnet client for BBS (Bulletin Board System) interactions with auto-learning capabilities. Enables AI agents to interact with legacy telnet-based systems through the Model Context Protocol (MCP).

⚠️ AI-Generated Code Disclaimer

This project was generated using AI assistance. While functional, it may contain bugs, security vulnerabilities, or unexpected behavior. Use at your own risk. The author assumes no responsibility or liability for any issues, damages, or losses resulting from the use of this software. Review the code thoroughly before using in any production environment.

Overview

bbsbot bridges modern AI agents with vintage BBS systems by providing:

• Full terminal emulation with ANSI/CP437 support
• Pattern-based screen reading and navigation
• Automatic discovery and documentation of menus and prompts
• Session logging for analysis and replay
• MCP tool exposure for seamless AI integration

Architecture

bbsbot uses a clean layered architecture with proper separation of concerns:

graph TB
    subgraph "AI Agent"
        LLM[Claude/LLM]
        MCP[MCP Client]
    end

    subgraph "bbsbot Server"
        App[FastMCP App]
        SM[SessionManager]

        subgraph "Core Layer"
            Session[Session]
        end

        subgraph "Transport Layer"
            Transport[TelnetTransport]
        end

        subgraph "Terminal Layer"
            Emulator[TerminalEmulatorpyte]
        end

        subgraph "Learning Layer"
            Engine[LearningEngine]
            Discovery[Menu Discovery]
        end

        subgraph "Logging Layer"
            Logger[SessionLogger]
        end
    end

    subgraph "BBS System"
        Telnet[Telnet Server :23]
        BBS[BBS Software]
    end

    subgraph "Knowledge Base"
        Prompts[prompt-catalog.md]
        Menus[menu-map.md]
        Flows[navigation-flows.md]
    end

    LLM --> MCP
    MCP -->|MCP Tools| App
    App --> SM
    SM --> Session
    Session --> Transport
    Session --> Emulator
    Session --> Engine
    Session --> Logger
    Transport -->|RFC 854 + IAC Escaping| Telnet
    Telnet --> BBS
    BBS -->|ANSI/CP437| Telnet
    Telnet -->|Raw Bytes| Transport
    Transport --> Emulator
    Engine --> Discovery
    Engine --> Prompts
    Engine --> Menus
    Engine --> Flows

Architecture Layers

• Transport Layer (transport/): Protocol abstraction (telnet with RFC 854 compliance, IAC byte escaping)
• Terminal Layer (terminal/): ANSI/CP437 terminal emulation using pyte
• Core Layer (core/): Session management with resource limits and state isolation
• Learning Layer (learning/): Auto-discovery of menus/prompts, knowledge base management
• Logging Layer (logging/): Structured JSONL session logging with raw bytes

Features

• Telnet Client: Full RFC 854 telnet protocol with option negotiation (BINARY, SGA, NAWS, TTYPE)
• Terminal Emulation: Complete ANSI/CP437 terminal with 80x25 (configurable) screen buffer
• Screen Reading: Extract text, match patterns, wait for prompts with timeout control
• Auto-Learning: Discover menus [A] Option, prompts Enter name:, and document navigation flows
• Session Logging: JSONL format with timestamps, context, and raw bytes for replay/analysis
• MCP Integration: 25+ tools for connection, navigation, learning, and session management
• Keepalive: Configurable interval to prevent idle disconnections

Installation

Prerequisites

Install uv (recommended package installer):

curl -LsSf https://astral.sh/uv/install.sh | sh

Or see uv installation docs for other methods.

Installing bbsbot

bbsbot is an MCP server that must be configured in your MCP client (Claude Desktop, Cline, etc.).

Option 1: Install as a tool (recommended)

uv tool install bbsbot

Then add to your MCP client configuration:

{
  "mcpServers": {
    "bbsbot_local_tw2002": {
      "command": "bbsbot"
    }
  }
}

Local TW2002 MCP vs External MCP Connectors

bbsbot provides TW2002 tools locally, but those tools only exist in the MCP server process you start from this repository/environment. In multi-connector clients, you may also have unrelated MCP connectors installed; those will not expose tw2002_* tools.

For swarm runtime/ROI diagnostics and anti-collapse control references, see:

• `docs/guides/SWARM_OPERATIONS_TELEMETRY.md`

Use an explicit local alias and tool filter for TW2002 operations:

{
  "mcpServers": {
    "bbsbot_local_tw2002": {
      "command": "bbsbot",
      "args": ["serve", "--tools", "tw2002"]
    }
  }
}

If tw2002_* tools are missing, first verify the configured command includes serve --tools tw2002.

Option 2: Install with pip

pip install bbsbot

Then configure y