intro & instructions

README.md

@@ -12,7 +12,51 @@ tags:
   - building-mcp-track-customer
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Aileen 3 Core
+## Introduction
+Large Language Models (LLMs) rely on **tools** - sometimes provided by **MCP servers** - to interact with the outside world. Aileen 3 Core is an MCP server that advances the goals of **Information Foraging**: mining for novel insights from high-noise sources to create dense briefings for time efficient consumption by the user.
+
+Aileen 3 Core is [a contender](https://huggingface.co/spaces/ndurner/aileen3-core) in the [MCP's 1st Birthday - Hosted by Anthropic and Gradio](https://huggingface.co/MCP-1st-Birthday) hackathon. [Aileen 3 Agent](https://github.com/ndurner/aileen3-agent), an agentic system built on this MCP server, is a [capstone project](https://ndurner.de/links/aileen3-kaggle-writeup) to the [AI Agents Intensive Course with Google](https://www.kaggle.com/learn-guide/5-day-agents).
+
+## Using
+### Using in Claude Desktop
+#### Installing
+1. Optionally, create a new Python virtual environment
+  * example: `python3 -m venv .venv-claude`
+2. Install the Aileen MCP: `pip install ./mcp`
+  * (or `pip install -e ./mcp` if you want to make live changes to this source tree)
+3. Obtain Google Gemini API key: [https://aistudio.google.com](Google AI Studio)
+3. Add reference to `claude_desktop_config.json`. The Gemini API key will be read from the environment, so can be set here:
+```
+{
+...
+  "mcpServers": {
+    "aileen3-mcp": {
+      "command": "/Users/.../aileen3-core/.venv-claude/bin/python",
+      "args": [
+        "-m",
+        "aileen3_mcp.server"
+      ],
+      "env": {
+        "GEMINI_API_KEY": "AI..."
+      }
+    }
+  }
+}
+```
+4. Restart Claude
+
+#### Using the MCP server
+The model Haiku 4.5 is sufficient for basic tasks. To make your plans fully transparent to the LLM, refer to "aileen3" explicitely in the prompt, e.g.:
+> Use aileen3 to translate slide 3 from YouTube video reference eXP-PvKcI9A to German.
+
+![Screenshot of Claude Desktop: slide translation with Aileen 3 Core](readme-assets/claude-slide-translation.webp)
+
+#### Debugging
+The message exchange and Claude-facing error messages can be read from Claude log files:
+```
+tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
+```
 
 ## Local development