MCP Server Examples

Model Context Protocol (MCP) server examples with simplified, focused tool sets. This repository contains working examples for Obsidian vault management and browser automation.

Status:

• Obsidian Examples: Production-ready ✅
• AWS Browser Example: Production-ready with real AWS Agent Core integration ✅
• Playwright Browser Example: Production-ready ✅

🚀 Quick Start

1. Clone and setup

   git clone <repository-url>
   cd mcp_server_examples
   make setup-all  # Installs dependencies and builds all examples

2. Configure your MCP client to use run.sh files as entry points

   • Each example has a run.sh that handles virtual environments automatically
   • Use absolute paths to these .sh files in your MCP client configuration

3. Test your setup using the commands below

📁 Available Servers

Obsidian Vault Management

• Python (FastMCP): examples/obsidian_python/run.sh
• TypeScript (Official SDK): examples/obsidian_typescript/run.sh

Tools: list, read, create, update, move, search, delete

Browser Automation

• Python (FastMCP + AWS Agent Core): examples/aws_agent_core_browser_python/run.sh
• TypeScript (AWS Agent Core): examples/aws_agent_core_browser_typescript/run.sh

Tools: fetch, screenshot

⚙️ Setup Instructions

Obsidian Servers

Prerequisites

• Obsidian with LiveSync plugin configured
• CouchDB server running (local or remote)

Python Setup

cd examples/obsidian_python
pip install -r requirements.txt

# Set environment variables
export VAULT_BASE_URL="http://localhost:5984"
export VAULT_DB_NAME="your-obsidian-vault"
export VAULT_USERNAME="your-username"  # optional
export VAULT_PASSWORD="your-password"  # optional

TypeScript Setup

cd examples/obsidian_typescript
npm install
npm run build

# Set same environment variables as Python

Browser Servers

Python (AWS Agent Core)

cd examples/aws_agent_core_browser_python
pip install -r requirements.txt

# Optional AWS configuration
export AWS_PROFILE="your-profile"
export AWS_REGION="us-west-2"

TypeScript (AWS Agent Core)

cd examples/aws_agent_core_browser_typescript
npm install
npx playwright install chromium
npm run build

🔧 Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian-python": {
      "command": "/absolute/path/to/examples/obsidian_python/run.sh",
      "env": {
        "VAULT_BASE_URL": "http://localhost:5984",
        "VAULT_DB_NAME": "your-vault-name",
        "VAULT_USERNAME": "your-username",
        "VAULT_PASSWORD": "your-password"
      }
    },
    "aws-browser": {
      "command": "/absolute/path/to/examples/aws_agent_core_browser_typescript/run.sh",
      "env": {}
    }
  }
}

Continue.dev

Add to your config.json:

{
  "mcpServers": [
    {
      "name": "obsidian-python",
      "command": ["/absolute/path/to/examples/obsidian_python/run.sh"],
      "env": {
        "VAULT_BASE_URL": "http://localhost:5984",
        "VAULT_DB_NAME": "your-vault-name",
        "VAULT_USERNAME": "your-username",
        "VAULT_PASSWORD": "your-password"
      }
    },
    {
      "name": "aws-browser",
      "command": ["/absolute/path/to/examples/aws_agent_core_browser_typescript/run.sh"],
      "env": {}
    }
  ]
}

MCP Inspector (Development)

npx @modelcontextprotocol/inspector examples/obsidian_python/run.sh

📋 Makefile Commands

Use the provided Makefile for easy path management:

make show-paths          # Show all absolute paths
make claude-config       # Generate Claude Desktop config
make continue-config     # Generate Continue.dev config  
make test-obsidian-py    # Test Obsidian Python server
make test-browser-ts     # Test TypeScript browser server

🔍 Testing Your Setup

Quick Test Commands

# Test Obsidian Python server
echo '{"method": "tools/list"}' | examples/obsidian_python/run.sh

# Test AWS Browser TypeScript server  
echo '{"method": "tools/list"}' | examples/aws_agent_core_browser_typescript/run.sh

Using MCP Inspector

# Interactive testing interface
npx @modelcontextprotocol/inspector examples/obsidian_python/run.sh

🌟 Example Usage

Obsidian Vault Operations

# List all files
list()

# Read a specific note
read("daily/2024-01-15.md")

# Create a new note
create("ideas/new-project.md", "# New Project\n\nGreat idea!")

# Search for files
search("*.md")

Browser Automation

# Fetch webpage content
fetch("https://example.com")

# Take a screenshot
screenshot("https://github.com")

🔧 Environment Variables

Obsidian Servers

Variable	Description	Required
VAULT_BASE_URL	CouchDB server URL	Yes
VAULT_DB_NAME	Database/vault name	Yes
VAULT_USERNAME	Auth username	No
VAULT_PASSWORD	Auth password	No

Browser Servers

Variable	Description	Default
AWS_PROFILE	AWS profile name	None
AWS_REGION	AWS region	us-west-2

🏗️ Architecture

Entry Points

• .sh files: All examples use run.sh as entry points
• Virtual environments: Shell scripts automatically activate Python venvs and handle dependencies
• Path independence: No need to manage Python/Node paths manually

Clean Tool Design

• Obsidian: 7 core file operations (CRUD + search/move)
• Browser: 2 focused tools (fetch content + screenshot)

Framework Choices

• Python: FastMCP for clean, decorator-based API
• TypeScript: Official MCP SDK for maximum compatibility

Error Handling

• Comprehensive error catching and user-friendly messages
• Automatic connection management and retries
• Graceful fallbacks (e.g., Playwright when AWS Agent Core unavailable)

📚 Individual READMEs

Each example directory contains detailed documentation:

• examples/obsidian_python/README.md
• examples/obsidian_typescript/README.md
• examples/aws_agent_core_browser_python/README.md
• examples/aws_agent_core_browser_typescript/README.md

🤝 Contributing

1. Fork the repository
2. Create your feature branch
3. Follow the existing code style and architecture
4. Add tests and documentation
5. Submit a pull request

📄 License

MIT License - See individual example directories for implementation details.