paws-on

Paws-on-MCP is a Python-based MCP server implementing the MCP 2025-03-26 specification. It exposes a rich set of MCP features, including tools for HackerNews and GitHub data gathering, a suite of resources for data sources, prompts templates for guided interactions, and enhanced sampling capabilities with model preferences. You can test and use the server locally via its HTTP API endpoints (notably under /mcp/). The CLI client (src/mcp_cli_client.py) is provided to exercise the available tools, resources, and sampling workflows from the command line. The server supports enhanced sampling with model hints, intelligence/cost/speed preferences, and server-context integration to tailor results per run.

To interact with the server, run it locally and then use the CLI or your own client to invoke tools like search_hackernews, get_github_repo_info, create_sampling_request, analyze_hackernews_trends_with_ai, and the resource endpoints such as hackernews://top/5, github://trending/python/daily, or sampling://repositories/python/3. The tooling is designed to demonstrate end-to-end MCP workflows: discovery of resources, execution of tools, prompt-driven reasoning, and context-aware sampling with model preferences. The server also exposes status and analysis resources to monitor health and results across runs.

Prerequisites:

• Python 3.8+ installed on your system
• Pip installed
• Network access to install dependencies

Steps:

1. Create and activate a virtual environment (optional but recommended):

   • macOS/Linux: python3 -m venv venv source venv/bin/activate
   • Windows: python -m venv venv .\venv\Scripts\activate

2. Install Python dependencies from requirements.txt: pip install -r requirements.txt

3. Run the MCP server: python src/mcp_server.py

4. (Optional) Test with the included CLI client: cd src python mcp_cli_client.py --help

5. Access the server at: http://127.0.0.1:8000/mcp/

Notes:

• The repository includes a comprehensive test suite under tests/ that demonstrates tools, resources, prompts, roots, and enhanced sampling. You can run these tests with the provided Python runner (python tests/run_tests.py).
• If you encounter port or binding issues, ensure no other process is occupying port 8000 and that firewall settings allow local connections.

Tips and common issues:

• Enhanced sampling relies on model preferences (e.g., Intelligence, Cost, Speed). Use the sampling tools to specify these priorities when creating a sampling request.
• Some tests indicate concurrency limitations under load. When deploying, monitor server load and consider running multiple instances behind a load balancer if needed.
• The CLI client can be used for rapid experimentation with tools like search_hackernews, get_github_repo_info, and create_sampling_request. Use the --help flag to discover available commands and arguments.
• Resources include HackerNews and GitHub integrations; when running outside localhost, ensure network access to the external APIs.
• If you modify prompts or roots, re-run the test suite to verify MCP protocol compliance and overall behavior.