thefaftek-git/mcp_notes_server

mcp_notes_server/ ├── app/ │ ├── main.py # FastAPI app │ ├── models.py # Pydantic Note model │ └── storage.py # JSON file storage logic ├── data/ │ └── notes.json # Notes storage (created at runtime) ├── tests/ │ └── test_notes.py # Test suite ├── requirements.txt ├── .gitignore └── README.md

MCP Notes Server

A Model Context Protocol (MCP) server for accepting and storing notes in a JSON file. Built with FastAPI and Python 3.10+.

Technology Stack

• Python 3.10+
• FastAPI (web framework)
• Uvicorn (ASGI server)
• Pydantic (data validation)
• pytest, httpx (testing)

Project Structure

mcp_notes_server/
├── app/
│   ├── main.py         # FastAPI app
│   ├── models.py       # Pydantic Note model
│   └── storage.py      # JSON file storage logic
├── data/
│   └── notes.json      # Notes storage (created at runtime)
├── tests/
│   └── test_notes.py   # Test suite
├── requirements.txt
├── .gitignore
└── README.md

Setup & Installation

1. Clone the repository

   git clone <repo-url>
   cd mcp_notes_server
   

2. Create and activate a virtual environment

   python3 -m venv venv
   source venv/bin/activate
   

3. Install dependencies

   pip install -r requirements.txt
   

Configuration

• Notes Storage:
  • By default, notes are stored in data/notes.json.
  • To change the storage location, set the NOTES_FILE environment variable:

    export NOTES_FILE=/path/to/your/notes.json
    

• Directory Structure:
  • All required folders are created automatically if missing.
• Port:
  • Default server port is 8000. Change with --port <number> when running uvicorn.
• Environment Variables:
  • NOTES_FILE (optional): Path to the notes JSON file.

Running the Server

From the project root (/home/nathan/plan1):

source mcp_notes_server/venv/bin/activate
PYTHONPATH=$(pwd)/mcp_notes_server uvicorn mcp_notes_server.app.main:app --reload --port 8000

• Access the API at: http://127.0.0.1:8000
• Interactive API docs: http://127.0.0.1:8000/docs

API Usage

POST /notes

• Request Body:

  {
    "text": "This is a note.",
    "timestamp": "2025-07-22T12:34:56Z",  // optional
    "user_id": "user123"                  // optional
  }
  

• Response:
  • 201 Created on success: { "message": "Note saved successfully." }
  • 400/422 for invalid input
  • 500 for server errors

Example curl

curl -X POST http://127.0.0.1:8000/notes \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world!", "user_id": "alice"}'

Testing

Run all tests:

source venv/bin/activate
pytest

• Tests cover valid/invalid note submissions and file handling.

Troubleshooting

• ModuleNotFoundError: No module named 'app'
  • Make sure to set PYTHONPATH as shown above when running the server.
• Permission errors:
  • Ensure the data/ directory is writable by the server process.
• Dependencies missing:
  • Run pip install -r requirements.txt in your virtual environment.
• Port conflicts:
  • Use --port <number> to specify a different port.

Extending the Project

• Add endpoints for reading/searching notes.
• Implement authentication and authorization.
• Support multiple users or sessions.
• Add data backup and recovery features.
• Integrate with a conversational agent app.
• Use a database for scalability if needed.

License

MIT (or specify your own)