mcp-observer-server is a prototype MCP (Model Context Protocol) server that watches your file system for changes and pushes notifications to MCP clients in real time. It leverages a Watchdog-based observer to monitor specified files and directories, exposing resources and change events through MCP-compliant endpoints. Clients can subscribe to a path to receive change notifications, read file contents, and query basic resource listings. The server is designed to be used with Inspector (a capable MCP client) via stdio transport, though any MCP client that supports resource subscriptions can connect and subscribe to resources such as individual files or directories. The workflow centers on the client subscribing to a path, and the server pushing timestamped notifications when a change is detected, enabling lightweight, proactive AI or automation interactions when your codebase or documents are modified.

Prerequisites:

• Python 3.8+ installed on your system
• git installed
• (optional) a Python virtual environment tool (venv/virtualenv)

Step-by-step:

1. Clone the repository: git clone https://github.com/hesreallyhim/mcp-observer-server.git cd mcp-observer-server

2. Install dependencies:

   • If using a virtual environment: python -m venv venv source venv/bin/activate # on Unix/macOS .\venv\Scripts\activate # on Windows
   • Then install requirements (adjust if a requirements.txt exists): pip install -r requirements.txt
   • If there is a pyproject.toml, you can install via: pip install -e .

3. Ensure the source path is discoverable by Python:

   • The project expects the module to be importable as mcp_observer_server.server. If you follow the repo layout, you may need to add the src directory to PYTHONPATH: export PYTHONPATH=src

     or on Windows:

     set PYTHONPATH=src

4. Run the server (development mode): python -m mcp_observer_server.server

5. Optional: run the development server with debugging/logging enabled by setting environment variables as needed (e.g., LOG_LEVEL).

Note: This is a minimal, demonstration-oriented setup. For production-like usage, consider containerizing or running within a virtual environment, and ensure the watched paths exist and are accessible by the Python process.

Tips and troubleshooting:

• The default demo file is watched.txt located at src/mcp_observer_server/watched.txt. It is git-ignored; create it before subscribing if you want to test changes.
• Subscriptions are managed per path. Use the Inspector client to list resources, then subscribe to a file or directory path to receive change notifications.
• If you don’t see events, verify that Watchdog is installed and that the path being watched exists and is accessible by the running process.
• The server is described as a lightweight POC focusing on real-time notifications. It may omit some of the richer MCP features (like full history) in the demo, but it demonstrates the subscription and notification flow.
• When testing with Inspector, use stdio as the transport. Ensure the Inspector client is configured to connect over stdio with the server’s process.
• If environment-specific issues arise, check PATH and Python versions, and ensure dependencies from requirements.txt or pyproject.toml are installed.