Improve README.md with badges, ToC, examples, and better documentation

Co-authored-by: ArthurDanjou <29738535+ArthurDanjou@users.noreply.github.com>

README.md

@@ -1,8 +1,44 @@
 # ArtMCP - Arthur Danjou's MCP Server
 
+[![Nuxt](https://img.shields.io/badge/Nuxt-4.2.2-00DC82?logo=nuxt.js&logoColor=white)](https://nuxt.com)
+[![License](https://img.shields.io/badge/License-Private-red.svg)](LICENSE)
+[![Deployment](https://img.shields.io/badge/Deployed%20on-Cloudflare-F38020?logo=cloudflare&logoColor=white)](https://hub.nuxt.com)
+[![MCP](https://img.shields.io/badge/Protocol-MCP-blue)](https://modelcontextprotocol.io)
+
 A comprehensive [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server exposing professional profile information about Arthur Danjou. Built with [Nuxt](https://nuxt.com) and deployed on [NuxtHub](https://hub.nuxt.com) at the Edge.
 
 🔗 **Live Server**: https://api.arthurdanjou.fr/mcp  
+📚 **Documentation**: https://api.arthurdanjou.fr/docs
+
+---
+
+## 📋 Table of Contents
+
+- [What is ArtMCP?](#-what-is-artmcp)
+- [Features](#-features)
+- [Architecture](#-architecture)
+- [Getting Started](#-getting-started)
+- [API Endpoints](#-api-endpoints)
+- [MCP Integration](#-mcp-integration)
+- [Development](#-development)
+- [Content Structure](#-content-structure)
+- [Technologies](#-technologies)
+- [Contributing](#-contributing)
+- [License](#-license)
+- [About](#-about)
+
+---
+
+## 💡 What is ArtMCP?
+
+ArtMCP is a **Model Context Protocol (MCP) server** that provides AI assistants and applications with structured, real-time access to professional information about Arthur Danjou. Instead of manually updating information across multiple platforms, this server acts as a single source of truth that can be queried by AI assistants, chatbots, or any application supporting MCP.
+
+**Use Cases:**
+- 🤖 Enable AI assistants to answer questions about Arthur's experience and skills
+- 📄 Automatically generate customized resumes and cover letters
+- 📊 Display real-time coding statistics and activity status
+- 🔍 Query specific information (projects, education, contact details) programmatically
+- 🌐 Integrate professional data into portfolios, websites, or applications
 
 ## 🎯 Features
 
@@ -53,12 +89,16 @@ This project uses:
 
 ### Prerequisites
 
-- Node.js 18+ or Bun
+- Node.js 18+ or Bun runtime
-- pnpm 10.12.1+
+- pnpm 10.12.1+ (package manager)
 
 ### Installation
 
 ```bash
+# Clone the repository
+git clone https://github.com/ArthurDanjou/artapi.git
+cd artapi
+
 # Install dependencies
 pnpm install
 ```
@@ -92,6 +132,11 @@ Start the development server on `http://localhost:3000`:
 pnpm dev
 ```
 
+The server will be available at:
+- 🌐 Web Interface: `http://localhost:3000`
+- 📚 Documentation: `http://localhost:3000/docs`
+- 🔌 MCP Endpoint: `http://localhost:3000/mcp`
+
 ### Production
 
 Build the application for production:
@@ -100,6 +145,12 @@ Build the application for production:
 pnpm build
 ```
 
+Preview the production build locally:
+
+```bash
+pnpm preview
+```
+
 ### Deployment
 
 Deploy to NuxtHub/Cloudflare:
@@ -108,38 +159,96 @@ Deploy to NuxtHub/Cloudflare:
 pnpm deploy
 ```
 
+> **Note:** Make sure you have proper Cloudflare credentials configured via `wrangler` CLI.
+
 ## 📚 API Endpoints
 
-All resources are also available as REST API endpoints:
+All resources are also available as REST API endpoints. Base URL: `https://api.arthurdanjou.fr`
 
-- `GET /api/skills`
+### Profile & Info
-- `GET /api/experiences`
+- `GET /api/profile` - Comprehensive profile with bio, location, availability, career goals
-- `GET /api/projects`
+- `GET /api/contact` - Professional contact information and social links
-- `GET /api/education`
+- `GET /api/skills` - Complete list of technical skills
-- `GET /api/languages`
+- `GET /api/languages` - Spoken languages with proficiency levels
-- `GET /api/profile`
+- `GET /api/hobbies` - Personal interests and activities
-- `GET /api/hobbies`
+
-- `GET /api/contact`
+### Professional Experience
-- `GET /api/uses`
+- `GET /api/experiences` - Professional work experience and projects
-- `GET /api/activity`
+- `GET /api/projects` - Portfolio of personal and professional projects
-- `GET /api/wakatime`
+- `GET /api/education` - Academic background and degrees
-- `GET /api/status-page`
+
-- `GET /api/resumes/{en|fr}` - Download resume
+### Real-time Data
+- `GET /api/activity` - Current activity and status (Discord integration)
+- `GET /api/wakatime` - Detailed coding statistics and analytics
+- `GET /api/status-page` - Homelab infrastructure status and uptime
+
+### Tools & Resources
+- `GET /api/uses` - Tools, hardware, and software setup
+- `GET /api/resumes/{en|fr}` - Download resume in English or French
+
+### Example Request
+
+```bash
+# Get profile information
+curl https://api.arthurdanjou.fr/api/profile
+
+# Get technical skills
+curl https://api.arthurdanjou.fr/api/skills
+
+# Download English resume
+curl -O https://api.arthurdanjou.fr/api/resumes/en
+```
+
+### Example Response
+
+```json
+{
+  "name": "Arthur Danjou",
+  "title": "Data Science & Applied AI Student",
+  "location": "Paris, France",
+  "availability": "Available for final-year internship (April 2026)",
+  "bio": "Rigorous, curious, and motivated...",
+  ...
+}
+```
 
 ## 🧪 Development
 
 ### Linting
 
+Check and fix code style issues:
+
 ```bash
+# Run ESLint
 pnpm lint
+
+# Auto-fix issues where possible
+pnpm lint --fix
 ```
 
 ### Type Checking
 
+Verify TypeScript types:
+
 ```bash
+# Type check without emitting files
 npx tsc --noEmit --skipLibCheck
+
+# Or use Vue's type checker
+npx vue-tsc --noEmit
 ```
 
+### Adding Content
+
+Content is managed in the `content/` directory. To add new items:
+
+1. **Add a new experience:** Create a markdown file in `content/experiences/`
+2. **Add a new project:** Create a markdown file in `content/projects/`
+3. **Update skills:** Edit `content/skills.json`
+4. **Update profile:** Edit `content/profile.md`
+
+Content changes are automatically picked up by Nuxt Content and reflected in the API.
+
 ## 📂 Content Structure
 
 Content is managed in the `content/` directory:
@@ -169,12 +278,19 @@ content/
 
 ## 📖 MCP Integration
 
-To use this server with an MCP client:
+### Connecting to ArtMCP
 
-1. Configure your MCP client to connect to `https://api.arthurdanjou.fr/mcp`
+To use this server with an MCP-compatible client:
-2. Or use the API directly via REST endpoints
+
+**Option 1: Direct URL Connection**
+```
+https://api.arthurdanjou.fr/mcp
+```
+
+**Option 2: Configuration File**
+
+Add to your MCP client configuration (e.g., Claude Desktop, Cline, etc.):
 
-Example MCP client configuration:
 ```json
 {
   "mcpServers": {
@@ -185,9 +301,112 @@ Example MCP client configuration:
 }
 ```
 
+### Using MCP Features
+
+Once connected, your AI assistant can:
+
+**Query Resources:**
+```
+"Show me Arthur's technical skills"
+"What projects has Arthur worked on?"
+"Get Arthur's contact information"
+```
+
+**Call Tools:**
+```
+"What is Arthur currently working on?" → Uses activity tool
+"Show Arthur's coding statistics" → Uses stats tool
+"Get Arthur's resume in French" → Uses resume-link tool
+```
+
+**Use Prompts:**
+```
+Pre-configured prompts guide the AI on how to query specific information
+about skills, experiences, projects, and more.
+```
+
+### Testing the Connection
+
+You can test the MCP endpoint is working:
+
+```bash
+# Test MCP server availability
+curl https://api.arthurdanjou.fr/mcp
+
+# Or visit in browser (redirects to /docs)
+open https://api.arthurdanjou.fr/mcp
+```
+
+## ❓ Troubleshooting & FAQ
+
+### Common Issues
+
+**Q: The development server won't start**
+- Ensure you have Node.js 18+ installed
+- Try removing `node_modules` and `pnpm-lock.yaml`, then run `pnpm install` again
+- Check if port 3000 is already in use
+
+**Q: Environment variables not working**
+- Copy `.env.example` to `.env`
+- Ensure all required variables are set (though most are optional)
+- Restart the development server after changing `.env`
+
+**Q: Content changes not reflecting**
+- The Nuxt Content module caches content. Try restarting the dev server
+- For production builds, clear the `.nuxt` and `.output` directories
+
+**Q: MCP endpoint returns 404**
+- Ensure the `@nuxtjs/mcp-toolkit` module is properly installed
+- Check that `browserRedirect` is configured in `nuxt.config.ts`
+- The MCP endpoint should redirect to `/docs` when accessed via browser
+
+**Q: Deployment to Cloudflare fails**
+- Verify Cloudflare credentials are configured with `wrangler login`
+- Check `wrangler.jsonc` for proper configuration
+- Ensure you have the necessary permissions on your Cloudflare account
+
+### Getting Help
+
+- 📖 Check the [documentation page](https://api.arthurdanjou.fr/docs)
+- 🐛 [Open an issue](https://github.com/ArthurDanjou/artapi/issues) on GitHub
+- 💬 Review existing issues for similar problems
+
 ## 🤝 Contributing
 
-This is a personal portfolio project. Feel free to use it as inspiration for your own MCP server!
+This is a personal portfolio project. However, contributions are welcome!
+
+### How to Contribute
+
+1. **Fork the repository**
+2. **Create a feature branch:** `git checkout -b feature/amazing-feature`
+3. **Make your changes** and commit: `git commit -m 'Add amazing feature'`
+4. **Push to your branch:** `git push origin feature/amazing-feature`
+5. **Open a Pull Request**
+
+### Ideas for Contributions
+
+- 🐛 Bug fixes
+- 📝 Documentation improvements
+- ✨ New MCP tools or resources
+- 🎨 UI/UX enhancements for the docs page
+- 🔧 Performance optimizations
+
+### Code Style
+
+This project uses:
+- **ESLint** for code linting (single quotes, no trailing commas)
+- **TypeScript** for type safety
+- **Vue 3** Composition API
+
+Run `pnpm lint` before submitting PRs.
+
+### Using as a Template
+
+Feel free to fork this project and adapt it for your own professional profile! Just:
+1. Update content in the `content/` directory
+2. Modify `nuxt.config.ts` with your settings
+3. Update environment variables for integrations (Discord, WakaTime, etc.)
+4. Deploy to your own Cloudflare account
 
 ## 📝 License