Merge pull request #8 from ArthurDanjou/copilot/improve-readme-file

Refactor README to focus on portfolio API with MCP as a component
2026-01-14 14:24:21 +01:00 · 2025-12-17 09:59:47 +01:00
parent fe542c95d3 92718bfe8e
commit 7f22229af1
1 changed files with 297 additions and 82 deletions
--- a/README.md
+++ b/README.md
@@ -1,66 +1,125 @@
-# ArtMCP - Arthur Danjou's MCP Server
+# ArtAPI - Arthur Danjou's Portfolio API

-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.
+[![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)
+[![Deployment](https://img.shields.io/badge/Deployed%20on-Cloudflare-F38020?logo=cloudflare&logoColor=white)](https://www.cloudflare.com/)
+[![MCP](https://img.shields.io/badge/Protocol-MCP-blue)](https://modelcontextprotocol.io)

-🔗 **Live Server**: https://api.arthurdanjou.fr/mcp
+A comprehensive REST API exposing professional profile information about Arthur Danjou. Built with [Nuxt](https://nuxt.com) and deployed on [NuxtHub](https://hub.nuxt.com) at the Edge. The API powers Arthur's portfolio and includes a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server component for AI assistant integration.

-## 🎯 Features
+🔗 **Base URL**: https://api.arthurdanjou.fr
+📚 **Documentation**: https://api.arthurdanjou.fr/docs
+🤖 **MCP Server**: https://api.arthurdanjou.fr/mcp

-### MCP Resources
+---

-The server exposes the following resources through the Model Context Protocol:
+## 📋 Table of Contents

- **📊 Skills** (`resource://artmcp/skills`) - Complete list of technical skills (programming languages, frameworks, tools)
- **💼 Experiences** (`resource://artmcp/experiences`) - Professional work experience and projects
- **🚀 Projects** (`resource://artmcp/projects`) - Portfolio of personal and professional projects
- **🎓 Education** (`resource://artmcp/education`) - Academic background and degrees
- **🌐 Languages** (`resource://artmcp/languages`) - Spoken languages with proficiency levels
- **👤 Profile** (`resource://artmcp/profile`) - Comprehensive profile with bio, location, availability, career goals, and work preferences
- **🎨 Hobbies** (`resource://artmcp/hobbies`) - Personal interests and activities
- **📞 Contact** (`resource://artmcp/contact`) - Professional contact information and social links
- **🛠️ Uses** (`resource://artmcp/uses`) - Tools, hardware, and software setup
+- [What is ArtAPI?](#-what-is-artapi)
+- [API Endpoints](#-api-endpoints)
+- [Getting Started](#-getting-started)
+- [Architecture](#-architecture)
+- [MCP Server Component](#-mcp-server-component)
+- [Development](#-development)
+- [Content Structure](#-content-structure)
+- [Troubleshooting & FAQ](#-troubleshooting--faq)
+- [Contributing](#-contributing)
+- [License](#-license)
+- [About](#-about)

-### MCP Tools
+---

- **`activity`** - Real-time current activity and status of Arthur Danjou
- **`resume-link`** - Get download link for resume in English or French
- **`stats`** - Detailed coding statistics and analytics from WakaTime
- **`status-page`** - Real-time status and uptime monitoring for homelab infrastructure
- **`uses-by-category`** - Filter uses by category (homelab, ide, hardware, software)
- **`weather`** - Get current weather for a city
+## 💡 What is ArtAPI?

-### MCP Prompts
+ArtAPI is a **comprehensive REST API** that serves as the backend for Arthur Danjou's portfolio. It provides structured access to professional information including skills, experiences, projects, education, and real-time activity data. The API is designed to power portfolio websites, applications, and integrations.

-Pre-configured prompts for common queries about:
- Resume generation
- Skills and expertise
- Projects showcase
- Real-time activity
- Contact information
- And more...
+**Key Features:**
+- 📊 **Portfolio Data**: Complete professional profile, skills, experiences, and projects
+- 🎓 **Education & Background**: Academic history and achievements
+- ⚡ **Real-time Data**: Current activity status and coding statistics via integrations
+- 📄 **Resume Access**: Download resumes in multiple languages
+- 🤖 **MCP Integration**: Optional Model Context Protocol server for AI assistant access
+- 🌐 **RESTful Design**: Clean, well-documented API endpoints

-## 🏗️ Architecture
+**Use Cases:**
+- 🌐 Power portfolio websites and applications
+- 📱 Build mobile apps showcasing professional information
+- 🤖 Enable AI assistants to answer questions about Arthur's experience
+- 📊 Display real-time coding statistics and activity dashboards
+- 🔍 Query specific information programmatically for integrations

-This project uses:
- **Nuxt 4** with Nitro for server-side rendering
- **@nuxt/content** for content management
- **@nuxtjs/mcp-toolkit** for MCP server implementation
- **NuxtHub** for edge deployment on Cloudflare Workers
- **nuxt-studio** for content management studio
- **Zod** for schema validation
+## 📚 API Endpoints
+
+All API endpoints are available at the base URL: `https://api.arthurdanjou.fr`
+
+### Profile & Information
+- `GET /api/profile` - Comprehensive profile with bio, location, availability, career goals
+- `GET /api/contact` - Professional contact information and social links
+- `GET /api/skills` - Complete list of technical skills (programming languages, frameworks, tools)
+- `GET /api/languages` - Spoken languages with proficiency levels
+- `GET /api/hobbies` - Personal interests and activities
+
+### Professional Experience
+- `GET /api/experiences` - Professional work experience and projects
+- `GET /api/projects` - Portfolio of personal and professional projects
+- `GET /api/education` - Academic background and degrees
+
+### Real-time Data
+- `GET /api/activity` - Current activity and status (Discord integration)
+- `GET /api/wakatime` - Detailed coding statistics and analytics from WakaTime
+- `GET /api/status-page` - Homelab infrastructure status and uptime monitoring
+
+### Tools & Resources
+- `GET /api/uses` - Tools, hardware, and software setup
+- `GET /api/resumes/{en|fr}` - Download resume in English or French
+
+### Example Usage
+
+```bash
+# Get profile information
+curl https://api.arthurdanjou.fr/api/profile
+
+# Get technical skills
+curl https://api.arthurdanjou.fr/api/skills
+
+# Get current activity
+curl https://api.arthurdanjou.fr/api/activity
+
+# 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...",
+  ...
+}
+```

 ## 🚀 Getting Started

 ### Prerequisites

- Node.js 18+ or Bun
- pnpm 10.12.1+
+- Bun 1.0+ (JavaScript runtime and package manager)
+- Alternatively: Node.js 18+ with pnpm 10.12.1+
+
+> **Note:** This project uses Bun as the primary runtime and package manager. Node.js with pnpm can be used as an alternative.

 ### Installation

 ```bash
+# Clone the repository
+git clone https://github.com/ArthurDanjou/artapi.git
+cd artapi
+
 # Install dependencies
-pnpm install
+bun install
 ```

 ### Environment Variables
@@ -89,15 +148,26 @@ NUXT_STATUS_PAGE=""
 Start the development server on `http://localhost:3000`:

 ```bash
-pnpm dev
+bun 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:

 ```bash
-pnpm build
+bun run build
+```
+
+Preview the production build locally:
+
+```bash
+bun preview
 ```

 ### Deployment
@@ -105,41 +175,146 @@ pnpm build
 Deploy to NuxtHub/Cloudflare:

 ```bash
-pnpm deploy
+# First time: Login to Cloudflare
+wrangler login
+
+# Deploy the application
+bun deploy
 ```

-## 📚 API Endpoints
+> **Note:** Make sure you have proper Cloudflare credentials configured. Run `wrangler login` to authenticate if this is your first deployment.

-All resources are also available as REST API endpoints:
+## 🏗️ Architecture

- `GET /api/skills`
- `GET /api/experiences`
- `GET /api/projects`
- `GET /api/education`
- `GET /api/languages`
- `GET /api/profile`
- `GET /api/hobbies`
- `GET /api/contact`
- `GET /api/uses`
- `GET /api/activity`
- `GET /api/wakatime`
- `GET /api/status-page`
- `GET /api/resumes/{en|fr}` - Download resume
+ArtAPI is built with modern web technologies and follows a serverless architecture:
+
+**Core Stack:**
+- **Nuxt 4** - Full-stack framework with Nitro for server-side rendering and API routes
+- **Vue 3** - Frontend framework (for documentation pages)
+- **Cloudflare Workers** - Edge deployment via NuxtHub for global low-latency access
+- **TypeScript** - Type-safe development
+
+**Data & Content:**
+- **Nuxt Content** - Content management with markdown and JSON files
+- **Cloudflare D1** - SQLite-compatible database for content queries in production
+- **Zod** - Schema validation for API responses
+
+**Additional Features:**
+- **@nuxtjs/mcp-toolkit** - Model Context Protocol server implementation
+- **nuxt-studio** - Content management studio interface
+- **Discord/WakaTime APIs** - Real-time integrations for activity and stats
+
+**Architecture Benefits:**
+- ⚡ **Fast**: Edge deployment on Cloudflare's global network
+- 🔒 **Type-safe**: Full TypeScript coverage
+- 📝 **Content-first**: Easy to update via markdown/JSON files
+- 🌐 **Multi-protocol**: REST API + MCP server in one package
+- 🚀 **Scalable**: Serverless architecture with automatic scaling
+
+## 🤖 MCP Server Component
+
+In addition to the REST API, ArtAPI includes a **Model Context Protocol (MCP) server** component that enables AI assistants and MCP-compatible applications to access the same data through the MCP protocol.
+
+**MCP Endpoint**: `https://api.arthurdanjou.fr/mcp`
+
+### Why MCP?
+
+The MCP server allows AI assistants (like Claude Desktop, Cline, etc.) to directly query Arthur's professional information, making it easy to:
+- Answer questions about experience and skills
+- Generate customized resumes and cover letters
+- Access real-time activity and coding statistics
+- Query specific information through natural language
+
+### MCP Resources
+
+The MCP server exposes all API data as resources:
+
+- **📊 Skills** (`resource://artmcp/skills`) - Technical skills and tools
+- **💼 Experiences** (`resource://artmcp/experiences`) - Work experience
+- **🚀 Projects** (`resource://artmcp/projects`) - Project portfolio
+- **🎓 Education** (`resource://artmcp/education`) - Academic background
+- **🌐 Languages** (`resource://artmcp/languages`) - Spoken languages
+- **👤 Profile** (`resource://artmcp/profile`) - Complete profile
+- **🎨 Hobbies** (`resource://artmcp/hobbies`) - Personal interests
+- **📞 Contact** (`resource://artmcp/contact`) - Contact information
+- **🛠️ Uses** (`resource://artmcp/uses`) - Tech stack and tools
+
+### MCP Tools
+
+Dynamic tools for AI assistants:
+
+- **`activity`** - Get current real-time activity status
+- **`resume-link`** - Get resume download link (English/French)
+- **`stats`** - Retrieve WakaTime coding statistics
+- **`status-page`** - Check homelab infrastructure status
+- **`uses-by-category`** - Filter tools by category
+- **`weather`** - Get weather for a city
+
+### Connecting via MCP
+
+**Option 1: Direct URL**
+```
+https://api.arthurdanjou.fr/mcp
+```
+
+**Option 2: Configuration File**
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "artapi": {
+      "url": "https://api.arthurdanjou.fr/mcp"
+    }
+  }
+}
+```
+
+**Usage Examples:**
+```
+"Show me Arthur's technical skills"
+"What is Arthur currently working on?"
+"Get Arthur's resume in French"
+```

 ## 🧪 Development

 ### Linting

+Check and fix code style issues:
+
 ```bash
-pnpm lint
+# Run ESLint
+bun lint
+
+# Auto-fix issues where possible
+bun 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:
@@ -158,36 +333,76 @@ content/
 └── uses/*.md                # Tools and setup
 ```

-## 🔧 Technologies
+## ❓ Troubleshooting & FAQ

- **Frontend/Backend**: Nuxt 4, Vue 3, Nitro
- **MCP**: @nuxtjs/mcp-toolkit
- **Content**: Nuxt Content with better-sqlite3
- **Content Studio**: nuxt-studio
- **Deployment**: Cloudflare Workers via NuxtHub
- **Validation**: Zod schemas
+### Common Issues

-## 📖 MCP Integration
+**Q: The development server won't start**
+- Ensure you have Bun 1.0+ installed
+- Try removing `node_modules` and `bun.lockb`, then run `bun install` again
+- Check if port 3000 is already in use

-To use this server with an MCP client:
+**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`

-1. Configure your MCP client to connect to `https://api.arthurdanjou.fr/mcp`
-2. Or use the API directly via REST endpoints
+**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

-Example MCP client configuration:
-```json
-{
-  "mcpServers": {
-    "artmcp": {
-      "url": "https://api.arthurdanjou.fr/mcp"
-    }
-  }
-}
-```
+**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 `bun 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