add mcp and gradio app

.agent/docs/common_core_spec.md

@@ -1,136 +0,0 @@
-This is the authoritative **Common Core Data Specification**. It contains the exact source locations, data schemas, field definitions, and the specific processing logic required to interpret the hierarchy correctly.
-
-**Use this document as the source of truth for `tools/build_data.py`.**
-
----
-
-# Data Specification: Common Core Standards
-
-**Authority:** Common Standards Project (GitHub)
-**License:** Creative Commons Attribution 4.0 (CC BY 4.0)
-**Format:** JSON (Flat List of Objects)
-
-## 1. Source Locations
-
-We are using the "Clean Data" export from the Common Standards Project. These files are static JSON dumps where each file represents a full Subject.
-
-| Subject            | Direct Download URL                                                                                                          |
-| :----------------- | :--------------------------------------------------------------------------------------------------------------------------- |
-| **Mathematics**    | `https://raw.githubusercontent.com/commoncurriculum/common-standards-project/master/data/clean-data/CCSSI/Mathematics.json`  |
-| **ELA / Literacy** | `https://raw.githubusercontent.com/commoncurriculum/common-standards-project/master/data/clean-data/CCSSI/ELA-Literacy.json` |
-
----
-
-## 2. The Data Structure (Glossary)
-
-The JSON file contains a root object. The actual standards are located in the `standards` dictionary, keyed by their internal GUID.
-
-### **Root Object**
-
-```json
-{
-  "subject": "Mathematics",
-  "standards": {
-    "6051566A...": { ... }, // Standard Object
-    "5E367098...": { ... }  // Standard Object
-  }
-}
-```
-
-### **Standard Object (The Item)**
-
-Each item represents a node in the curriculum tree. It could be a broad **Domain**, a grouping **Cluster**, or a specific **Standard**.
-
-| Field Name              | Type            | Definition & Usage                                                                                                                    |
-| :---------------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
-| **`id`**                | `String (GUID)` | The internal unique identifier. Used for lookups in `ancestorIds`.                                                                    |
-| **`statementNotation`** | `String`        | **The Display Code.** (e.g., `CCSS.Math.Content.1.OA.A.1`). This is what teachers recognize. Use this for the UI.                     |
-| **`description`**       | `String`        | The text content. **Warning:** For standards, this text is often incomplete without its parent context (see Hierarchy below).         |
-| **`statementLabel`**    | `String`        | The hierarchy type. Critical values: <br>• `Domain` (Highest) <br>• `Cluster` (Grouping) <br>• `Standard` (The actionable item)       |
-| **`gradeLevels`**       | `Array[String]` | Scope of the standard. <br>• Format: `["01", "02"]` (Grades 1 & 2), `["K"]` (Kindergarten), `["09", "10", "11", "12"]` (High School). |
-| **`ancestorIds`**       | `Array[GUID]`   | **CRITICAL.** An ordered list of parent IDs (from root to immediate parent). You must resolve these to build the full context.        |
-
----
-
-## 3. Hierarchy & Context (The "Interpretation" Problem)
-
-**The Problem:**
-A standard's description often relies on its parent "Cluster" for meaning.
-
-- _Cluster Text:_ "Understand the place value system."
-- _Standard Text:_ "Recognize that in a multi-digit number, a digit in one place represents 10 times as much..."
-
-If you only embed the _Standard Text_, the vector will miss the concept of "Place Value."
-
-**The Solution (Processing Logic):**
-To generate the **Search String** for embedding, you must concatenate the hierarchy.
-
-1.  **Domain:** The broad category (e.g., "Number and Operations in Base Ten").
-2.  **Cluster:** The specific topic (e.g., "Generalize place value understanding").
-3.  **Standard:** The task.
-
-**Formula:**
-
-```text
-"{Subject} {Grade}: {Domain Text} - {Cluster Text} - {Standard Text}"
-```
-
----
-
-## 4. Build Pipeline Specification (`tools/build_data.py`)
-
-This specific logic ensures we extract meaningful vectors.
-
-### **Step A: Ingestion**
-
-1.  Download both JSON files.
-2.  Merge the `standards` dictionaries into a single **Lookup Map** (Memory: `Map<GUID, Object>`).
-
-### **Step B: Iteration & Filtering**
-
-Iterate through the Lookup Map.
-**Filter Rule:**
-
-- **KEEP** if `statementLabel` equals `"Standard"`.
-- **DISCARD** if `statementLabel` is `"Domain"`, `"Cluster"`, or `"Component"`. (We only index the actionable leaves).
-
-### **Step C: Context Resolution (The "Breadcrumb" Loop)**
-
-For every kept Standard:
-
-1.  Initialize `context_text = ""`
-2.  Iterate through `ancestorIds`:
-    - Use the ID to look up the Parent Object in the **Lookup Map**.
-    - Append `Parent.description` to `context_text`.
-3.  Construct the final string:
-    - `full_text = f"{context_text} {current_standard.description}"`
-4.  **Vectorize `full_text`**.
-
-### **Step D: Output Schema (`data/standards.json`)**
-
-The clean, flat JSON file you save for the App to load must look like this:
-
-```json
-[
-  {
-    "id": "CCSS.Math.Content.1.OA.A.1", // From 'statementNotation'
-    "guid": "6051566A...", // From 'id'
-    "grade": "01", // From 'gradeLevels[0]'
-    "subject": "Mathematics", // From 'subject'
-    "description": "Use addition and subtraction within 20 to solve word problems...", // From 'description'
-    "full_context": "Operations and Algebraic Thinking - Represent and solve problems... - Use addition and..." // The text we used for embedding
-  }
-]
-```
-
----
-
-## 5. Summary of Valid `gradeLevels`
-
-When processing, normalize these strings if necessary, but typically they appear as:
-
-- `K` (Kindergarten)
-- `01` - `08` (Grades 1-8)
-- `09-12` (High School generic)
-
-_Note: If `gradeLevels` is an array `["09", "10", "11", "12"]`, you can display it as "High School" or "Grades 9-12"._

.agent/specs/002_mcp/spec.md

@@ -0,0 +1,574 @@
+# MCP Server Sprint Specification
+
+## Overview
+
+This sprint builds the MCP (Model Context Protocol) server that exposes the Pinecone database of educational standards to MCP clients (e.g., Claude Desktop). The server provides two methods of interacting with the Pinecone database:
+
+1. **Semantic Search**: Vector similarity search using natural language queries to find relevant standards
+2. **Direct ID Lookup**: Retrieve a specific standard by its GUID or identifier
+
+---
+
+## MCP Server Architecture
+
+### Entry Point
+
+The MCP server will be implemented as `server.py` in the project root. This file is minimal and focused on:
+
+- Setting up the FastMCP server instance
+- Defining tool decorators that delegate to logic in `src/`
+- Running the server
+
+The bulk of the logic lives in the `src/` directory, which serves as the authoritative location for shared code.
+
+### Framework
+
+Use `mcp.server.fastmcp.FastMCP` for the MCP server implementation. This provides a simple decorator-based API for defining tools.
+
+### Code Organization
+
+**Separation of Concerns:**
+
+- `server.py` (root): Server setup, tool definitions, and delegation to `src/` modules
+- `src/`: Authoritative location for all business logic, including Pinecone client and tool implementations
+- `tools/`: CLI tools that import shared logic from `src/`
+
+### Pinecone Client Migration
+
+Move `tools/pinecone_client.py` to `src/pinecone_client.py`. Update all imports in `tools/` to import from `src.pinecone_client` instead. This establishes `src/` as the definitive source for Pinecone interaction logic.
+
+### Configuration
+
+Create a configuration module `src/mcp_config.py` that wraps or duplicates Pinecone configuration settings. This provides isolation from the CLI tools configuration.
+
+**Configuration Requirements:**
+
+- `PINECONE_API_KEY`: Pinecone API key (required)
+- `PINECONE_INDEX_NAME`: Name of the Pinecone index (default: `common-core-standards`)
+- `PINECONE_NAMESPACE`: Namespace for records (default: `standards`)
+
+---
+
+## MCP Tools
+
+The server exposes two tools matching the MVP spec interface:
+
+### Tool 1: `find_relevant_standards`
+
+Performs semantic search over educational standards using vector similarity.
+
+**Parameters:**
+
+- `activity` (str, required): Natural language description of the learning activity
+- `max_results` (int, optional, default: 5): Maximum number of standards to return
+- `grade` (str, optional): Grade level filter (e.g., "K", "01", "05", "09")
+- `subject` (str, optional): Subject filter (e.g., "Mathematics", "ELA-Literacy")
+
+**Implementation:**
+
+- Use Pinecone's `search()` method with integrated embeddings (`llama-text-embed-v2`)
+- Pass the user's query text via `query={"inputs": {"text": activity}, "top_k": max_results}`
+- Embeddings are generated automatically by Pinecone
+- Apply metadata filters inside the query dict: `"filter": {...}` (only include key if filters exist)
+- Always rerank results using `rerank={"model": "bge-reranker-v2-m3", "top_n": max_results, "rank_fields": ["content"]}`
+- Access results via `results['result']['hits']`, extracting `_id`, `_score`, and `fields` from each hit
+- Return top N matches sorted by reranked relevance score
+
+**Response Format:**
+Returns a JSON string with structured format:
+
+```json
+{
+  "success": true,
+  "results": [
+    {
+      "_id": "EA60C8D165F6481B90BFF782CE193F93",
+      "content": "...",
+      "subject": "Mathematics",
+      "education_levels": ["01"],
+      "statement_notation": "CCSS.Math.Content.1.OA.A.1",
+      "standard_set_title": "...",
+      "score": 0.85
+    }
+  ],
+  "message": "Found 5 matching standards"
+}
+```
+
+### Tool 2: `get_standard_details`
+
+Retrieves a specific standard by its GUID or identifier.
+
+**Parameters:**
+
+- `standard_id` (str, required): The standard's GUID (`_id` field) or identifier
+
+**Implementation:**
+
+- Use Pinecone's `fetch()` method with the standard's GUID (`_id` field)
+- If the identifier is not a GUID, may need to query by metadata filter on `statement_notation` or `asn_identifier` fields
+
+**Response Format:**
+Returns a JSON string with structured format:
+
+```json
+{
+  "success": true,
+  "results": [
+    {
+      "_id": "EA60C8D165F6481B90BFF782CE193F93",
+      "content": "...",
+      "subject": "Mathematics",
+      "education_levels": ["01"],
+      "statement_notation": "CCSS.Math.Content.1.OA.A.1",
+      "standard_set_title": "...",
+      "all_metadata_fields": "..."
+    }
+  ],
+  "message": "Retrieved standard details"
+}
+```
+
+---
+
+## Error Handling
+
+All tools catch exceptions and return structured error responses with `error_type` fields:
+
+**Error Response Format:**
+
+```json
+{
+  "success": false,
+  "results": [],
+  "message": "Error description",
+  "error_type": "error_category"
+}
+```
+
+**Valid `error_type` values:**
+
+- `no_results`: Query returned no matches
+- `invalid_input`: Malformed input (empty string, invalid ID format, etc.)
+- `api_error`: Pinecone API failure or connection error
+- `not_found`: Standard ID doesn't exist (for `get_standard_details`)
+
+For `get_standard_details` with invalid ID, include a helpful suggestion:
+
+```json
+{
+  "success": false,
+  "results": [],
+  "message": "Standard 'XYZ.123' not found. Try using find_relevant_standards with a keyword search instead.",
+  "error_type": "not_found"
+}
+```
+
+---
+
+## Pinecone Integration
+
+### Implementation Approach
+
+Use the shared `PineconeClient` class from `src/pinecone_client.py`. The MCP server and CLI tools both import and use this shared client, ensuring consistency and avoiding code duplication. The `src/` directory is the authoritative location for Pinecone interaction logic.
+
+### Extending PineconeClient
+
+Add search and fetch methods to `src/pinecone_client.py`:
+
+- `search_standards()`: Semantic search with filters
+- `fetch_standard()`: Direct ID lookup
+
+These methods encapsulate the Pinecone query logic and can be used by both the MCP server and CLI tools.
+
+### Semantic Search Implementation
+
+- Use Pinecone's `search()` method with integrated embeddings
+- The index is configured with `llama-text-embed-v2` model and `field_map text=content`
+- Pass query text to Pinecone's `search()` method using the `inputs` parameter - embeddings are generated automatically
+- Always rerank results using the `bge-reranker-v2-m3` model for improved relevance
+- Build filter dictionary dynamically (only include filters with values):
+  - If `grade` provided: `{"education_levels": {"$in": [grade]}}`
+  - If `subject` provided: `{"subject": {"$eq": subject}}`
+  - Combine with `$and` if both: `{"$and": [grade_filter, subject_filter]}`
+- Add filter to query dict only if it exists: `query_dict["filter"] = filter_dict`
+- **Important**: Do not set `filter` to `None` — omit the key entirely when no filters
+
+### Direct ID Lookup Implementation
+
+- Use Pinecone's `fetch()` method with the standard's GUID (`_id` field)
+- The `_id` field corresponds to the standard's GUID from the source data
+
+### Pinecone Record Structure
+
+Records in Pinecone follow the `PineconeRecord` model structure:
+
+- `_id`: Standard GUID (string)
+- `content`: Text content for embedding (string)
+- `subject`: Subject name (string)
+- `education_levels`: List of grade levels (list[str])
+- `statement_notation`: CCSS notation if available (str | None)
+- `standard_set_id`, `standard_set_title`, `jurisdiction_id`, etc.: Additional metadata fields
+
+---
+
+## File Structure
+
+```
+common_core_mcp/
+├── server.py                    # MCP server entry point - minimal setup only (NEW)
+├── src/
+│   ├── pinecone_client.py      # Pinecone client (MOVED from tools/) (MODIFIED)
+│   ├── mcp_config.py          # MCP-specific configuration (NEW)
+│   ├── search.py               # Semantic search logic (NEW)
+│   └── lookup.py               # Direct ID lookup logic (NEW)
+├── tools/                       # CLI tools (MODIFIED - imports from src/)
+│   └── pinecone_client.py      # (REMOVED - moved to src/)
+├── data/                        # Existing data directory (unchanged)
+└── pyproject.toml               # Dependencies (mcp already included)
+```
+
+### Files to Create
+
+- **`server.py`** (project root): Minimal MCP server setup and tool definitions
+- **`src/mcp_config.py`**: MCP-specific configuration module
+- **`src/search.py`**: Semantic search implementation logic
+- **`src/lookup.py`**: Direct ID lookup implementation logic
+
+### Files to Move
+
+- **`tools/pinecone_client.py`** → **`src/pinecone_client.py`**: Move Pinecone client to authoritative `src/` location
+
+### Files to Modify
+
+- **`tools/cli.py`**: Update imports to use `from src.pinecone_client import PineconeClient` (replace `from tools.pinecone_client`)
+- **`tools/pinecone_processor.py`**: Update imports to use `from src.pinecone_client import PineconeClient` (replace `from tools.pinecone_client`)
+- **`src/pinecone_client.py`**: Add `search_standards()` and `fetch_standard()` methods for MCP server use
+- Any other files in `tools/` that import `pinecone_client`: Update to import from `src.pinecone_client`
+
+### Files to Reference (Existing)
+
+- **`tools/pinecone_models.py`**: Contains `PineconeRecord` model structure for reference (may also move to `src/` in future)
+- **`tools/config.py`**: Contains `ToolsSettings` for reference (but MCP uses separate config)
+
+---
+
+## Implementation Details
+
+### Server Entry Point (`server.py`)
+
+The `server.py` file should be minimal and focused on setup:
+
+1. Import FastMCP and create server instance:
+
+   ```python
+   from mcp.server.fastmcp import FastMCP
+   mcp = FastMCP("CommonCore")
+   ```
+
+2. Import tool logic functions from `src/` modules
+3. Define thin wrapper functions with `@mcp.tool()` decorator that delegate to `src/` logic
+4. Run server with `mcp.run()` when executed directly
+
+**Example Structure:**
+
+```python
+from mcp.server.fastmcp import FastMCP
+from src.search import find_relevant_standards_impl
+from src.lookup import get_standard_details_impl
+
+mcp = FastMCP("CommonCore")
+
+@mcp.tool()
+def find_relevant_standards(activity: str, max_results: int = 5, grade: str | None = None, subject: str | None = None) -> str:
+    """Returns educational standards relevant to the activity."""
+    return find_relevant_standards_impl(activity, max_results, grade, subject)
+
+@mcp.tool()
+def get_standard_details(standard_id: str) -> str:
+    """Returns full metadata for a standard by its GUID or identifier."""
+    return get_standard_details_impl(standard_id)
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+**Execution:**
+
+- Run with: `uv run server.py` or `python server.py`
+- Server communicates via stdio (FastMCP handles transport automatically)
+
+### Configuration Module (`src/mcp_config.py`)
+
+Create a configuration module that:
+
+- Loads environment variables from `.env` file
+- Provides settings for Pinecone connection (API key, index name, namespace)
+- Can duplicate or wrap settings from `tools/config.py` but maintains isolation
+
+**Function Signature:**
+
+```python
+def get_mcp_settings() -> McpSettings:
+    """Get MCP server configuration settings."""
+    # Returns settings object with pinecone_api_key, pinecone_index_name, pinecone_namespace
+```
+
+### Search Module (`src/search.py`)
+
+Contains the implementation logic for semantic search.
+
+**Function Signature:**
+
+```python
+def find_relevant_standards_impl(
+    activity: str,
+    max_results: int = 5,
+    grade: str | None = None,
+    subject: str | None = None
+) -> str:
+    """
+    Implementation of semantic search over educational standards.
+
+    Args:
+        activity: Description of the learning activity
+        max_results: Maximum number of standards to return (default: 5)
+        grade: Optional grade level filter (e.g., "K", "01", "05", "09")
+        subject: Optional subject filter (e.g., "Mathematics", "ELA-Literacy")
+
+    Returns:
+        JSON string with structured response containing matching standards
+    """
+    # Uses PineconeClient from src.pinecone_client
+    # Handles error cases and returns JSON response
+```
+
+### Lookup Module (`src/lookup.py`)
+
+Contains the implementation logic for direct ID lookup.
+
+**Function Signature:**
+
+```python
+def get_standard_details_impl(standard_id: str) -> str:
+    """
+    Implementation of direct standard lookup by ID.
+
+    Args:
+        standard_id: The standard's GUID (_id field) or identifier
+
+    Returns:
+        JSON string with structured response containing standard details
+    """
+    # Uses PineconeClient from src.pinecone_client
+    # Handles error cases and returns JSON response
+```
+
+### PineconeClient Extensions (`src/pinecone_client.py`)
+
+Add methods to the `PineconeClient` class (moved from `tools/`):
+
+**New Methods:**
+
+```python
+def search_standards(
+    self,
+    query_text: str,
+    top_k: int = 5,
+    grade: str | None = None,
+    subject: str | None = None
+) -> list[dict]:
+    """
+    Perform semantic search over standards.
+
+    Args:
+        query_text: Natural language query
+        top_k: Maximum number of results
+        grade: Optional grade filter
+        subject: Optional subject filter
+
+    Returns:
+        List of result dictionaries with metadata and scores
+    """
+
+def fetch_standard(self, standard_id: str) -> dict | None:
+    """
+    Fetch a standard by its GUID.
+
+    Args:
+        standard_id: Standard GUID (_id field)
+
+    Returns:
+        Standard dictionary with metadata, or None if not found
+    """
+```
+
+### Pinecone Query Implementation
+
+**Semantic Search Workflow (`src/search.py`):**
+
+1. Import `PineconeClient` from `src.pinecone_client`
+2. Initialize client instance (or use singleton pattern)
+3. Call `client.search_standards()` with parameters
+4. Format results into JSON response structure
+5. Handle errors and return appropriate error responses
+
+**Implementation in `PineconeClient.search_standards()` (`src/pinecone_client.py`):**
+
+1. Build Pinecone filter dictionary from optional parameters:
+   - If `grade` provided: Add `{"education_levels": {"$in": [grade]}}`
+   - If `subject` provided: Add `{"subject": {"$eq": subject}}`
+   - Combine filters with `$and` if both provided
+2. Build the query dictionary:
+   - `"inputs": {"text": query_text}` for text queries (embeddings generated automatically)
+   - `"top_k": top_k * 2` to get more candidates for reranking
+   - `"filter": filter_dict` only if filters are provided (omit key if no filters)
+3. Call `index.search()` with:
+   - `namespace=namespace` (from config)
+   - `query=query_dict` (the constructed query dictionary)
+   - `rerank={"model": "bge-reranker-v2-m3", "top_n": top_k, "rank_fields": ["content"]}` (always enabled)
+4. Access results via `results['result']['hits']`
+5. Extract `_id`, `_score`, and `fields` from each hit and return list of result dictionaries
+
+**Response Parsing:**
+
+Access search results via `results['result']['hits']`. Each hit contains:
+
+- `hit['_id']`: Record ID
+- `hit['_score']`: Reranked relevance score
+- `hit['fields']`: Dictionary of metadata fields (e.g., `hit['fields']['content']`, `hit['fields']['subject']`)
+
+Example parsing:
+
+```python
+for hit in results['result']['hits']:
+    record = {
+        "_id": hit["_id"],
+        "score": hit["_score"],
+        **hit["fields"]  # Spread all metadata fields
+    }
+```
+
+**Direct ID Lookup Workflow (`src/lookup.py`):**
+
+1. Import `PineconeClient` from `src.pinecone_client`
+2. Initialize client instance (or use singleton pattern)
+3. Call `client.fetch_standard()` with standard_id
+4. If found, format into JSON response structure
+5. If not found, return error response with `error_type: "not_found"`
+
+**Implementation in `PineconeClient.fetch_standard()` (`src/pinecone_client.py`):**
+
+1. Call `index.fetch()` with:
+   - `ids=[standard_id]`
+   - `namespace=namespace` (from config)
+2. Extract result from returned dictionary
+3. Return standard dictionary with metadata, or None if not found
+
+### Error Handling Implementation
+
+Error handling is implemented in the `src/` modules (`src/search.py` and `src/lookup.py`):
+
+**In `src/search.py` (`find_relevant_standards_impl`):**
+
+1. Validate input parameters (e.g., empty strings, None values)
+2. Wrap `PineconeClient.search_standards()` call in try/except
+3. Catch `PineconeException` and map to appropriate `error_type`
+4. Handle empty results case
+5. Return structured JSON error responses
+6. Never raise exceptions - always return JSON response
+
+**In `src/lookup.py` (`get_standard_details_impl`):**
+
+1. Validate input parameters (e.g., empty strings, None values)
+2. Wrap `PineconeClient.fetch_standard()` call in try/except
+3. Catch `PineconeException` and map to appropriate `error_type`
+4. Handle None result (not found)
+5. Return structured JSON error responses
+6. Never raise exceptions - always return JSON response
+
+**Error Mapping:**
+
+- `PineconeException` → `error_type: "api_error"`
+- Empty `activity` or `standard_id` → `error_type: "invalid_input"`
+- No results from query → `error_type: "no_results"`
+- ID not found in fetch (returns None) → `error_type: "not_found"`
+
+---
+
+## Dependencies
+
+The `mcp` package is already included in `pyproject.toml`. Ensure `pinecone` is also available (already included). No additional dependencies are required for this sprint.
+
+---
+
+## Running the Server
+
+### Local Development
+
+1. Ensure environment variables are set in `.env`:
+
+   ```
+   PINECONE_API_KEY=your_api_key_here
+   PINECONE_INDEX_NAME=common-core-standards
+   PINECONE_NAMESPACE=standards
+   ```
+
+2. Run the server:
+
+   ```bash
+   uv run server.py
+   ```
+
+   Or:
+
+   ```bash
+   python server.py
+   ```
+
+3. The server communicates via stdio. FastMCP handles the MCP protocol transport automatically.
+
+### Claude Desktop Integration
+
+To connect Claude Desktop to the local MCP server, add configuration:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "common-core": {
+      "command": "uv",
+      "args": ["run", "server.py"],
+      "cwd": "/absolute/path/to/common_core_mcp"
+    }
+  }
+}
+```
+
+**Important:** Replace `/absolute/path/to/common_core_mcp` with the actual absolute path to your project directory.
+
+---
+
+## Testing
+
+Skip tests for this sprint. Focus on getting the server working first. Tests can be added in a future sprint.
+
+### Manual Validation
+
+To validate the server works:
+
+1. Run `server.py` and verify it starts without errors
+2. Connect Claude Desktop and verify tools appear
+3. Test `find_relevant_standards` with a sample activity
+4. Test `get_standard_details` with a known GUID
+5. Test error cases (invalid ID, empty query, etc.)
+
+---
+
+## Limitations and Future Work
+
+- **Tools Only**: The MCP server only supports tools for now. Prompts and resources are not included in this sprint.
+- **No Reasoning**: The server does not include LLM reasoning/explanations for why standards match activities. This matches the MVP spec's `ask_llama` functionality but is deferred for now.
+- **Limited Filters**: Only `grade` and `subject` filters are supported initially. Additional filters (e.g., `is_leaf`, `standard_set_id`, `jurisdiction_id`) can be added in future sprints.

.agent/specs/002_mcp/tasks.md

@@ -0,0 +1,69 @@
+# Spec Tasks
+
+## Tasks
+
+- [x] 1. Create MCP Configuration Module
+
+  - [x] 1.1 Create `src/mcp_config.py` with `McpSettings` class using Pydantic BaseSettings
+  - [x] 1.2 Add `pinecone_api_key` (required), `pinecone_index_name` (default: "common-core-standards"), and `pinecone_namespace` (default: "standards") fields
+  - [x] 1.3 Configure to load from `.env` file with `env_file=".env"` and `env_file_encoding="utf-8"`
+  - [x] 1.4 Create `get_mcp_settings()` function that returns a singleton `McpSettings` instance
+  - [x] 1.5 Add validation to ensure `pinecone_api_key` is not empty (raise ValueError if missing)
+
+- [x] 2. Move PineconeClient to src/ Directory
+
+  - [x] 2.1 Move `tools/pinecone_client.py` to `src/pinecone_client.py`
+  - [x] 2.2 Update imports in `src/pinecone_client.py`: change `from tools.config import get_settings` to use `src.mcp_config.get_mcp_settings()` instead
+  - [x] 2.3 Update `PineconeClient.__init__()` to use `get_mcp_settings()` from `src.mcp_config`
+  - [x] 2.4 Verify `src/pinecone_client.py` imports `PineconeRecord` from `tools.pinecone_models` (keep this import for now)
+
+- [x] 3. Update Tools Imports to Use src.pinecone_client
+
+  - [x] 3.1 Update `tools/cli.py`: replace `from tools.pinecone_client import PineconeClient` with `from src.pinecone_client import PineconeClient` (2 occurrences)
+  - [x] 3.2 Check `tools/pinecone_processor.py` for any `pinecone_client` imports and update if present
+  - [x] 3.3 Verify all imports work correctly by checking for any remaining references to `tools.pinecone_client`
+
+- [x] 4. Add search_standards() Method to PineconeClient
+
+  - [x] 4.1 Add `search_standards()` method signature: `def search_standards(self, query_text: str, top_k: int = 5, grade: str | None = None, subject: str | None = None) -> list[dict]`
+  - [x] 4.2 Build filter dictionary dynamically: create empty list, add `{"education_levels": {"$in": [grade]}}` if grade provided, add `{"subject": {"$eq": subject}}` if subject provided, combine with `$and` if both exist
+  - [x] 4.3 Build query dictionary: `{"inputs": {"text": query_text}, "top_k": top_k * 2}` (double for reranking candidates), add `"filter": filter_dict` only if filter_dict exists
+  - [x] 4.4 Call `index.search()` with `namespace=self.namespace`, `query=query_dict`, and `rerank={"model": "bge-reranker-v2-m3", "top_n": top_k, "rank_fields": ["content"]}`
+  - [x] 4.5 Parse results: access `results['result']['hits']`, extract `_id`, `_score`, and `fields` from each hit, combine into dict with `{"_id": hit["_id"], "score": hit["_score"], **hit["fields"]}`
+  - [x] 4.6 Return list of result dictionaries
+
+- [x] 5. Add fetch_standard() Method to PineconeClient
+
+  - [x] 5.1 Add `fetch_standard()` method signature: `def fetch_standard(self, standard_id: str) -> dict | None`
+  - [x] 5.2 Call `index.fetch()` with `ids=[standard_id]` and `namespace=self.namespace`
+  - [x] 5.3 Extract result from `result.records` dictionary using `standard_id` as key
+  - [x] 5.4 If record found, extract `_id` and all fields from `record.fields`, combine into dict
+  - [x] 5.5 Return dictionary with metadata or `None` if not found
+
+- [x] 6. Create search.py Module with Semantic Search Implementation
+
+  - [x] 6.1 Create `src/search.py` with imports: `json`, `PineconeClient` from `src.pinecone_client`, `PineconeException` from `pinecone.exceptions`
+  - [x] 6.2 Implement `find_relevant_standards_impl()` function with signature matching spec (activity, max_results=5, grade=None, subject=None) -> str
+  - [x] 6.3 Add input validation: check if `activity` is empty or None, return error JSON with `error_type: "invalid_input"` if invalid
+  - [x] 6.4 Wrap `PineconeClient.search_standards()` call in try/except, catch `PineconeException` and return error JSON with `error_type: "api_error"`
+  - [x] 6.5 Handle empty results: if results list is empty, return error JSON with `error_type: "no_results"` and message "No matching standards found"
+  - [x] 6.6 Format successful results: create response dict with `success: True`, `results` list (each with `_id`, `score`, and all metadata fields), and `message` with count
+  - [x] 6.7 Return JSON string using `json.dumps()` with proper formatting
+
+- [x] 7. Create lookup.py Module with Direct ID Lookup Implementation
+
+  - [x] 7.1 Create `src/lookup.py` with imports: `json`, `PineconeClient` from `src.pinecone_client`, `PineconeException` from `pinecone.exceptions`
+  - [x] 7.2 Implement `get_standard_details_impl()` function with signature: `(standard_id: str) -> str`
+  - [x] 7.3 Add input validation: check if `standard_id` is empty or None, return error JSON with `error_type: "invalid_input"` if invalid
+  - [x] 7.4 Wrap `PineconeClient.fetch_standard()` call in try/except, catch `PineconeException` and return error JSON with `error_type: "api_error"`
+  - [x] 7.5 Handle not found: if `fetch_standard()` returns `None`, return error JSON with `error_type: "not_found"` and helpful message suggesting to use `find_relevant_standards`
+  - [x] 7.6 Format successful result: create response dict with `success: True`, `results` list containing single standard dict with all metadata, and `message: "Retrieved standard details"`
+  - [x] 7.7 Return JSON string using `json.dumps()` with proper formatting
+
+- [x] 8. Create server.py MCP Entry Point
+  - [x] 8.1 Create `server.py` in project root with imports: `FastMCP` from `mcp.server.fastmcp`, `find_relevant_standards_impl` from `src.search`, `get_standard_details_impl` from `src.lookup`
+  - [x] 8.2 Initialize FastMCP server: `mcp = FastMCP("CommonCore")`
+  - [x] 8.3 Define `find_relevant_standards` tool with `@mcp.tool()` decorator, signature matching spec (activity, max_results=5, grade=None, subject=None) -> str, docstring "Returns educational standards relevant to the activity"
+  - [x] 8.4 Define `get_standard_details` tool with `@mcp.tool()` decorator, signature `(standard_id: str) -> str`, docstring "Returns full metadata for a standard by its GUID or identifier"
+  - [x] 8.5 Add `if __name__ == "__main__": mcp.run()` block to start server
+  - [x] 8.6 Verify server starts without errors by running `uv run server.py`

.agent/specs/003_gradio/spec.md

@@ -0,0 +1,1167 @@
+# Gradio MCP Server Sprint Specification
+
+## Overview
+
+This sprint replaces the existing FastMCP server implementation with a Gradio-based MCP server that can be hosted publicly on Hugging Face Spaces. The Gradio app will expose the Common Core Standards MCP tools and include a chat interface that demonstrates MCP tool calling capabilities. This enables public access to the MCP server and provides a demonstration interface for the hackathon submission.
+
+## Key Changes
+
+- Replace `server.py` (FastMCP) with `app.py` (Gradio MCP server)
+- Update dependencies to use Gradio 6.0.0+ with MCP support
+- Remove FastMCP dependency from `pyproject.toml`
+- Create Hugging Face Space configuration files
+- Implement chat interface with MCP tool calling support
+- Update README to meet hackathon requirements
+
+## User Stories
+
+1. **As a developer**, I want to access the MCP server via a public Hugging Face Space URL so that I can use it from any MCP client without running it locally.
+
+2. **As a user**, I want to interact with a chat interface that can answer questions about educational standards using the MCP tools, so that I can see how the MCP server works in practice.
+
+3. **As a hackathon judge**, I want to see a working MCP server hosted on Hugging Face Spaces with proper documentation, so that I can evaluate the submission.
+
+## Technical Architecture
+
+### Gradio MCP Server Implementation
+
+Gradio 6 introduces native MCP server support. When `mcp_server=True` is set in `demo.launch()`, Gradio automatically:
+
+1. Converts each API endpoint (function) into an MCP tool
+2. Uses function docstrings and type hints to generate tool descriptions and parameter schemas
+3. Exposes the MCP server at `http://your-server:port/gradio_api/mcp/`
+4. Provides an SSE (Server-Sent Events) endpoint for MCP clients
+
+### Function to MCP Tool Conversion
+
+Gradio automatically converts functions with proper docstrings and type hints into MCP tools:
+
+- **Function name** → Tool name
+- **Docstring** → Tool description
+- **Type hints** → Parameter schema
+- **Default values** → Default parameter values (from component initial values)
+
+### MCP Server Endpoints
+
+When `mcp_server=True` is enabled:
+
+- **MCP Schema**: `http://your-server:port/gradio_api/mcp/schema`
+- **MCP SSE Endpoint**: `http://your-server:port/gradio_api/mcp/` (for MCP clients)
+- **MCP Documentation**: Available via "View API" link in Gradio app footer
+
+### MCP Server Activation
+
+**We will use the `demo.launch(mcp_server=True)` parameter approach** (not the environment variable method). This provides explicit control and makes the MCP server activation clear in the code.
+
+## Implementation Details
+
+### Dependencies Update
+
+**File: `pyproject.toml`**
+
+**Explicit Requirement**: Update Gradio dependency to version 6.0.0 or higher **with MCP extras**:
+
+```toml
+dependencies = [
+    "gradio[mcp]>=6.0.0",
+    "pinecone",
+    "python-dotenv",
+    "typer",
+    "requests",
+    "rich",
+    "loguru",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+    "huggingface_hub",
+]
+```
+
+**Important Notes:**
+
+- The `[mcp]` extra ensures all MCP dependencies are installed
+- Remove the standalone `mcp` package dependency if present (FastMCP is no longer used)
+- Add `huggingface_hub` for Inference API access in the chat interface
+
+### Gradio App Structure
+
+**File: `app.py`** (new file, replaces `server.py`)
+
+The Gradio app should:
+
+1. **Expose MCP Tools**: Create functions that wrap the existing `src/search.py` and `src/lookup.py` implementations
+2. **Enable MCP Server**: Set `mcp_server=True` in `demo.launch()`
+3. **Include Chat Interface**: Use `gr.ChatInterface` with a function that supports MCP tool calling
+
+**Function Requirements for MCP Tools:**
+
+- Functions must have detailed docstrings in the format:
+
+  ```python
+  def function_name(param1: type, param2: type) -> return_type:
+      """
+      Description of what the function does.
+
+      Args:
+          param1: Description of param1
+          param2: Description of param2
+
+      Returns:
+          Description of return value
+      """
+  ```
+
+- Type hints are required for all parameters
+- Default values can be set via component initial values (e.g., `gr.Textbox("default value")`)
+
+**Example Structure:**
+
+```python
+import gradio as gr
+from src.search import find_relevant_standards_impl
+from src.lookup import get_standard_details_impl
+
+def find_relevant_standards(
+    activity: str,
+    max_results: int = 5,
+    grade: str | None = None,
+    subject: str | None = None,
+) -> str:
+    """
+    Searches for educational standards relevant to a learning activity using semantic search.
+
+    This function performs a vector similarity search over the Common Core Standards database
+    to find standards that match the described learning activity. Results are ranked by relevance
+    and can be filtered by grade level and subject area.
+
+    Args:
+        activity: A natural language description of the learning activity, lesson, or educational
+            objective. Examples: "teaching fractions to third graders", "reading comprehension
+            activities", "solving quadratic equations". This is the primary search query and should
+            be descriptive and specific for best results.
+
+        max_results: The maximum number of standards to return. Must be between 1 and 20.
+            Default is 5. Higher values return more results but may include less relevant matches.
+
+        grade: Optional grade level filter. Must be one of the following valid grade level codes:
+            - "K" for Kindergarten
+            - "01" for Grade 1
+            - "02" for Grade 2
+            - "03" for Grade 3
+            - "04" for Grade 4
+            - "05" for Grade 5
+            - "06" for Grade 6
+            - "07" for Grade 7
+            - "08" for Grade 8
+            - "09" for Grade 9
+            - "10" for Grade 10
+            - "11" for Grade 11
+            - "12" for Grade 12
+            - "09-12" for high school range (when standards span multiple high school grades)
+
+            If None or empty string, no grade filtering is applied and standards from all grade
+            levels may be returned. The grade filter uses exact matching against the education_levels
+            metadata field in the database.
+
+        subject: Optional subject area filter. Common values include:
+            - "Mathematics" or "Math"
+            - "ELA-Literacy" or "English Language Arts"
+            - "Science"
+            - "Social Studies"
+            - Other subject names as they appear in the standards database
+
+            If None or empty string, no subject filtering is applied. The subject filter uses
+            case-insensitive matching against the subject metadata field.
+
+    Returns:
+        A JSON string containing a structured response with the following format:
+        {
+            "success": true|false,
+            "results": [
+                {
+                    "_id": "standard_guid",
+                    "content": "full standard text with hierarchy",
+                    "subject": "Mathematics",
+                    "education_levels": ["03"],
+                    "statement_notation": "3.NF.A.1",
+                    "standard_set_title": "Grade 3",
+                    "score": 0.85
+                },
+                ...
+            ],
+            "message": "Found N matching standards" or error message,
+            "error_type": null or error type if success is false
+        }
+
+        On success, the results array contains up to max_results standards, sorted by relevance
+        score (highest first). Each result includes the full standard content, metadata, and
+        relevance score. On error, success is false and an error message describes the issue.
+    """
+    # Handle empty string from dropdown (convert to None)
+    if grade == "":
+        grade = None
+    if subject == "":
+        subject = None
+
+    # Ensure max_results is an integer (gr.Number returns float by default)
+    max_results = int(max_results)
+
+    return find_relevant_standards_impl(activity, max_results, grade, subject)
+
+def get_standard_details(standard_id: str) -> str:
+    """
+    Retrieves complete metadata and content for a specific educational standard by its identifier.
+
+    This function performs a direct lookup of a standard using its unique identifier. The identifier
+    can be either the standard's GUID (a unique UUID-like string) or its statement notation
+    (the human-readable code like "3.NF.A.1" or "CCSS.Math.Content.3.NF.A.1").
+
+    Args:
+        standard_id: The unique identifier for the standard. This can be:
+            - A GUID (e.g., "EA60C8D165F6481B90BFF782CE193F93"): The internal database ID
+            - A statement notation (e.g., "3.NF.A.1"): The standard's notation code
+            - An ASN identifier (e.g., "S21238682"): If available in the standard's metadata
+
+            The function will attempt to match the identifier against multiple fields in the database.
+            GUIDs provide the fastest and most reliable lookup. Statement notations may match
+            multiple standards if the notation format is ambiguous.
+
+    Returns:
+        A JSON string containing a structured response with the following format:
+        {
+            "success": true|false,
+            "results": [
+                {
+                    "_id": "standard_guid",
+                    "content": "full standard text with hierarchy",
+                    "subject": "Mathematics",
+                    "education_levels": ["03"],
+                    "statement_notation": "3.NF.A.1",
+                    "standard_set_title": "Grade 3",
+                    "asn_identifier": "S21238682",
+                    "depth": 3,
+                    "is_leaf": true,
+                    "parent_id": "parent_guid",
+                    "ancestor_ids": [...],
+                    "child_ids": [...],
+                    ... (all available metadata fields)
+                }
+            ],
+            "message": "Retrieved standard details" or error message,
+            "error_type": null or error type if success is false
+        }
+
+        On success, the results array contains exactly one standard object with all available
+        metadata fields including hierarchy relationships, content, and identifiers. On error
+        (e.g., standard not found), success is false and the message provides guidance, such as
+        suggesting to use find_relevant_standards for searching.
+
+    Raises:
+        This function does not raise exceptions. All errors are returned as JSON responses
+        with success=false and appropriate error messages.
+    """
+    return get_standard_details_impl(standard_id)
+
+# Chat interface function - see complete implementation in Chat Interface Implementation section below
+
+# Create Gradio interface
+demo = gr.TabbedInterface(
+    [
+        gr.Interface(
+            fn=find_relevant_standards,
+            inputs=[
+                gr.Textbox(label="Activity Description", placeholder="Describe a learning activity..."),
+                gr.Number(label="Max Results", value=5, minimum=1, maximum=20),
+                gr.Dropdown(
+                    label="Grade (optional)",
+                    choices=["", "K", "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "09-12"],
+                    value=None,
+                    info="Select a grade level to filter results"
+                ),
+                gr.Textbox(label="Subject (optional)", placeholder="e.g., Mathematics, ELA-Literacy"),
+            ],
+            outputs=gr.JSON(label="Results"),
+            title="Find Relevant Standards",
+            description="Search for educational standards relevant to a learning activity.",
+            api_name="find_relevant_standards",
+        ),
+        gr.Interface(
+            fn=get_standard_details,
+            inputs=gr.Textbox(label="Standard ID", placeholder="Enter a standard GUID or identifier..."),
+            outputs=gr.JSON(label="Standard Details"),
+            title="Get Standard Details",
+            description="Retrieve full metadata for a specific standard by its ID.",
+            api_name="get_standard_details",
+        ),
+        gr.ChatInterface(
+            fn=chat_with_standards,  # See complete implementation in Chat Interface Implementation section
+            type="messages",  # Required in Gradio 6 - uses OpenAI-style message format
+            title="Chat with Standards",
+            description="Ask questions about educational standards. The AI will use MCP tools to find relevant information.",
+            examples=["What standards apply to teaching fractions in 3rd grade?", "Find standards for reading comprehension"],
+        ),
+    ],
+    ["Search", "Lookup", "Chat"],
+)
+
+if __name__ == "__main__":
+    demo.launch(mcp_server=True)
+```
+
+### Chat Interface Implementation
+
+**Priority: First Priority** - The chat interface is a required deliverable for this sprint.
+
+**Minimum Viable Implementation:**
+
+- Use Hugging Face Inference API with a free/open model that supports MCP tool calling
+- Model should be able to call the MCP tools (`find_relevant_standards` and `get_standard_details`)
+- Chat function should integrate with the MCP server to answer questions about educational requirements
+
+**Model Selection (Researched and Verified):**
+
+**Selected Model: `Qwen/Qwen2.5-7B-Instruct`**
+
+This model has been verified to:
+
+- Support tool/function calling via Hugging Face Inference API
+- Be available through Inference Providers (Together AI, Featherless AI)
+- Have good performance for chat applications
+- Support the OpenAI-compatible function calling format used by InferenceClient
+- Be actively maintained and widely used (57.9M+ downloads as of research date)
+
+**Important:** The model requires specifying an inference provider (e.g., `provider="together"` or `provider="nebius"`) when using InferenceClient.
+
+**Alternative (for more complex queries):** `Qwen/Qwen2.5-72B-Instruct` (larger, more capable, available via Nebius provider)
+
+**Implementation Details:**
+
+The chat function will use Hugging Face's `InferenceClient` with function calling. Since the MCP tools (`find_relevant_standards` and `get_standard_details`) are exposed by the same Gradio app, we can call them directly as Python functions rather than making HTTP requests to the MCP server endpoint. This is more efficient and simpler.
+
+**Complete Chat Function Implementation:**
+
+```python
+import os
+import json
+from typing import Any
+from huggingface_hub import InferenceClient
+from src.search import find_relevant_standards_impl
+from src.lookup import get_standard_details_impl
+
+# Initialize the Hugging Face Inference Client
+# Use HF_TOKEN from environment (automatically available in Hugging Face Spaces)
+# Provider is required for models that need Inference Providers (e.g., Together AI, Nebius)
+HF_TOKEN = os.environ.get("HF_TOKEN")
+client = InferenceClient(
+    provider="together",  # Required: specifies the inference provider for tool calling
+    token=HF_TOKEN
+)
+
+# Define the function schemas in OpenAI format for the model
+TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "find_relevant_standards",
+            "description": "Searches for educational standards relevant to a learning activity using semantic search. Use this when the user asks about standards for a specific activity, lesson, or educational objective.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "activity": {
+                        "type": "string",
+                        "description": "A natural language description of the learning activity, lesson, or educational objective. Be specific and descriptive."
+                    },
+                    "max_results": {
+                        "type": "integer",
+                        "description": "Maximum number of standards to return (1-20). Default is 5.",
+                        "default": 5,
+                        "minimum": 1,
+                        "maximum": 20
+                    },
+                    "grade": {
+                        "type": "string",
+                        "description": "Optional grade level filter. Valid values: K, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, or 09-12 for high school range.",
+                        "enum": ["K", "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "09-12"]
+                    },
+                    "subject": {
+                        "type": "string",
+                        "description": "Optional subject area filter (e.g., 'Mathematics', 'ELA-Literacy', 'Science')."
+                    }
+                },
+                "required": ["activity"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_standard_details",
+            "description": "Retrieves complete metadata and content for a specific educational standard by its identifier (GUID or statement notation). Use this when the user asks about a specific standard or wants details about a standard mentioned in previous results.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "standard_id": {
+                        "type": "string",
+                        "description": "The unique identifier for the standard. Can be a GUID (UUID-like string) or statement notation (e.g., '3.NF.A.1')."
+                    }
+                },
+                "required": ["standard_id"]
+            }
+        }
+    }
+]
+
+# Function registry for executing tool calls
+AVAILABLE_FUNCTIONS = {
+    "find_relevant_standards": find_relevant_standards_impl,
+    "get_standard_details": get_standard_details_impl,
+}
+
+def chat_with_standards(message: str, history: list) -> str:
+    """
+    Chat function that uses MCP tools via Hugging Face Inference API with tool calling.
+
+    This function integrates with Qwen2.5-7B-Instruct to answer questions about educational
+    standards. The model can call find_relevant_standards and get_standard_details tools
+    to retrieve information and provide accurate responses.
+
+    Args:
+        message: The user's current message/query
+        history: Chat history in Gradio 6 messages format. Each message is a dict with
+            "role" and "content" keys. In Gradio 6, content uses structured format:
+            [{"type": "text", "text": "..."}, ...] for text content.
+
+    Returns:
+        The assistant's response as a string, incorporating information from MCP tools
+        when relevant.
+    """
+    # Convert Gradio 6 history format to OpenAI messages format
+    # Gradio 6 uses structured content: {"role": "user", "content": [{"type": "text", "text": "..."}]}
+    messages = []
+    if history:
+        for msg in history:
+            if isinstance(msg, dict):
+                role = msg.get("role", "user")
+                content = msg.get("content", "")
+
+                # Handle Gradio 6 structured content format
+                if isinstance(content, list):
+                    # Extract text from content blocks
+                    text_parts = []
+                    for block in content:
+                        if isinstance(block, dict) and block.get("type") == "text":
+                            text_parts.append(block.get("text", ""))
+                    content = " ".join(text_parts)
+
+                messages.append({
+                    "role": role,
+                    "content": content
+                })
+
+    # Add system message to guide the model
+    system_message = {
+        "role": "system",
+        "content": "You are a helpful assistant that answers questions about educational standards. You have access to tools that can search for standards and retrieve standard details. Use these tools when users ask about standards, learning activities, or educational requirements. Always provide clear, helpful responses based on the tool results."
+    }
+
+    # Add current user message
+    messages.append({"role": "user", "content": message})
+
+    # Prepare full message list with system message
+    full_messages = [system_message] + messages
+
+    try:
+        # Initial API call with tools
+        response = client.chat.completions.create(
+            model="Qwen/Qwen2.5-7B-Instruct",
+            messages=full_messages,
+            tools=TOOLS,
+            tool_choice="auto",  # Let the model decide when to call functions
+            temperature=0.7,
+            max_tokens=1000,
+        )
+
+        response_message = response.choices[0].message
+
+        # Check if model wants to call functions
+        if response_message.tool_calls:
+            # Add assistant's tool call request to messages
+            full_messages.append(response_message)
+
+            # Process each tool call
+            for tool_call in response_message.tool_calls:
+                function_name = tool_call.function.name
+                function_args = json.loads(tool_call.function.arguments)
+
+                # Execute the function
+                if function_name in AVAILABLE_FUNCTIONS:
+                    if function_name == "find_relevant_standards":
+                        result = AVAILABLE_FUNCTIONS[function_name](
+                            activity=function_args.get("activity", ""),
+                            max_results=function_args.get("max_results", 5),
+                            grade=function_args.get("grade"),
+                            subject=function_args.get("subject")
+                        )
+                    elif function_name == "get_standard_details":
+                        result = AVAILABLE_FUNCTIONS[function_name](
+                            standard_id=function_args.get("standard_id", "")
+                        )
+                    else:
+                        result = json.dumps({"error": f"Unknown function: {function_name}"})
+                else:
+                    result = json.dumps({"error": f"Function {function_name} not available"})
+
+                # Add function result to messages
+                full_messages.append({
+                    "role": "tool",
+                    "tool_call_id": tool_call.id,
+                    "name": function_name,
+                    "content": result,
+                })
+
+            # Get final response with function results
+            final_response = client.chat.completions.create(
+                model="Qwen/Qwen2.5-7B-Instruct",
+                messages=full_messages,
+                temperature=0.7,
+                max_tokens=1000,
+            )
+
+            return final_response.choices[0].message.content
+        else:
+            # No tool calls, return direct response
+            return response_message.content
+
+    except Exception as e:
+        # Error handling
+        return f"I apologize, but I encountered an error: {str(e)}. Please try again or rephrase your question."
+```
+
+**Key Implementation Points:**
+
+1. **Direct Function Calls**: Since the MCP tools are in the same Python process, we call the underlying implementation functions (`find_relevant_standards_impl` and `get_standard_details_impl`) directly rather than making HTTP requests to the MCP server endpoint.
+
+2. **Tool Schema Conversion**: The MCP tools are converted to OpenAI function calling format, which is what `InferenceClient` expects. The schemas match the function signatures and docstrings.
+
+3. **Tool Calling Workflow**:
+
+   - First API call includes tools and lets model decide if/when to call them
+   - If model requests tool calls, execute them and add results to conversation
+   - Second API call generates final response incorporating tool results
+
+4. **Error Handling**: All errors are caught and returned as user-friendly messages.
+
+5. **Model Configuration**: Uses `Qwen/Qwen2.5-7B-Instruct` via Together AI provider with `tool_choice="auto"` to let the model decide when to use tools.
+
+6. **Gradio 6 History Format**: The chat function handles Gradio 6's structured content format where content is a list of typed blocks (e.g., `[{"type": "text", "text": "..."}]`) rather than simple strings.
+
+### Hugging Face Space Configuration
+
+**CRITICAL: Space must be created in the MCP-1st-Birthday organization**
+
+**Required Files:**
+
+1. **`app.py`**: Main Gradio application entry point (as described above)
+
+2. **`requirements.txt`**: Python dependencies
+
+   - Extract from `pyproject.toml` or manually specify
+   - Must include: `gradio[mcp]>=6.0.0`, `pinecone`, `python-dotenv`, `pydantic>=2.0.0`, `pydantic-settings>=2.0.0`, `huggingface_hub`
+   - The `[mcp]` extra ensures all MCP dependencies are included
+   - `huggingface_hub` is required for Inference API access in the chat interface
+
+3. **`README.md`**: Updated with hackathon requirements (see README Requirements section below)
+
+4. **`.env.example`**: Template for environment variables
+
+   ```
+   PINECONE_API_KEY=your_api_key_here
+   PINECONE_INDEX_NAME=common-core-standards
+   PINECONE_NAMESPACE=standards
+   HF_TOKEN=your_huggingface_token_here
+   # Note: MCP_SERVER_URL is not needed since we call functions directly
+   ```
+
+5. **Space Configuration** (via Hugging Face UI):
+   - **Organization**: Must be `MCP-1st-Birthday` (create Space in this organization)
+   - SDK: `gradio`
+   - Python version: 3.12+
+   - Environment variables: Set `PINECONE_API_KEY`, `HF_TOKEN`, and other required variables in Space settings
+   - **Visibility**: Can be public or private (both work for MCP servers)
+
+### Hackathon Registration and Submission Requirements
+
+**Before Building:**
+
+1. **Join the Organization** (REQUIRED):
+
+   - Go to https://huggingface.co/MCP-1st-Birthday
+   - Click "Request to join this org" (top right)
+   - Wait for approval (usually automatic or quick)
+
+2. **Complete Registration** (REQUIRED):
+
+   - Complete the official registration form (linked on the hackathon page)
+   - Registration link: Available on the hackathon page
+
+3. **Team Members** (if applicable):
+   - If working in a team (2-5 people), **all** members must:
+     - Join the MCP-1st-Birthday organization individually
+     - Complete the registration form individually
+     - Be listed in the README with their Hugging Face usernames
+
+**Submission Requirements (All Must Be Completed by November 30, 2025, 11:59 PM UTC):**
+
+1. **Hugging Face Space** (REQUIRED):
+
+   - Space must be in the `MCP-1st-Birthday` organization
+   - Space must be functional and accessible
+   - Code must be pushed to the Space repository
+
+2. **README.md** (REQUIRED):
+
+   - Must include track tag: `building-mcp-track-consumer`
+   - Must include team member usernames (if team)
+   - Must include demo video link
+   - Must include social media post link
+   - Must include clear documentation (see README Requirements section)
+
+3. **Demo Video** (REQUIRED):
+
+   - **Length:** 1-5 minutes
+   - **Content:** Must show the MCP server in action, specifically demonstrating:
+     - Integration with an MCP client (Claude Desktop, Cursor, or similar)
+     - The MCP tools being used through the client
+     - The Gradio web interface
+     - The chat interface using MCP tools
+   - **Hosting:** YouTube, Vimeo, or similar platform
+   - **Link:** Must be included in the README
+
+4. **Social Media Post** (REQUIRED):
+
+   - Post about your project on X/Twitter, LinkedIn, or similar
+   - Include information about the project and hackathon
+   - **Link:** Must be included in the README (not just submission form)
+
+5. **Functionality Requirements**:
+   - Working MCP server (exposed via Gradio)
+   - Integration with MCP client (demonstrated in video)
+   - Published as Hugging Face Space
+
+**Judging Criteria (To Guide Implementation):**
+
+Projects will be evaluated on:
+
+1. **Completeness**: Space, video, documentation, and social link all present
+2. **Functionality**: Works effectively, uses Gradio 6 and MCP features
+3. **Real-world Impact**: Useful tool with potential for real-world application
+4. **Creativity**: Innovative or original idea and implementation
+5. **Design/UI-UX**: Polished, intuitive, and easy to use
+6. **Documentation**: Well-communicated in README and/or demo video
+
+**Additional Considerations for Judging:**
+
+- **Community Choice Award**: Based on social media engagement, Space interactions (Discussions tab), and Discord community engagement
+- **Gradio 6 Features**: Use of Gradio 6 capabilities (MCP server, ChatInterface, etc.)
+- **MCP Integration**: Effective use of MCP protocol and tool exposure
+
+### README Requirements
+
+**File: `README.md`**
+
+The README is a critical component of the hackathon submission and must include all required elements. Follow this structure:
+
+#### 1. **Hackathon Track Tag (REQUIRED)**
+
+**Must be included in the README metadata or prominently at the top:**
+
+Add the track tag `building-mcp-track-consumer` to classify this as a Consumer MCP Server entry. This tag is **mandatory** for submission eligibility.
+
+**Placement options:**
+
+- In the README frontmatter (if using YAML frontmatter)
+- As a tag/badge at the top of the README
+- In a "Hackathon" or "Submission" section
+
+**Example:**
+
+```markdown
+---
+tags:
+  - building-mcp-track-consumer
+  - mcp
+  - gradio
+  - education
+---
+```
+
+Or as a badge:
+
+```markdown
+![Hackathon Track](https://img.shields.io/badge/Track-Consumer%20MCP%20Server-blue)
+```
+
+#### 2. **Project Title and Description**
+
+Clear, compelling explanation of:
+
+- What the MCP server does
+- Its purpose and capabilities
+- Why it's useful for consumers (teachers, students, parents, etc.)
+- Key features and benefits
+
+#### 3. **Team Information (If Applicable)**
+
+**If working in a team (2-5 members):**
+
+- Include Hugging Face usernames of **all** team members
+- Format: "Built by @username1, @username2, @username3"
+- All team members must be members of the MCP-1st-Birthday organization
+
+**If working solo:**
+
+- Optional: Include your Hugging Face username
+- Format: "Built by @username"
+
+#### 4. **Usage Instructions**
+
+**A. Gradio Web Interface:**
+
+- How to use the web interface
+- What each tab/component does
+- Example queries or use cases
+
+**B. MCP Client Integration (REQUIRED for demo video):**
+
+- How to connect an MCP client (Claude Desktop, Cursor, etc.) to the Space
+- MCP server URL: `https://your-space-name.hf.space/gradio_api/mcp/`
+- Step-by-step configuration instructions
+- Example MCP client configuration:
+  ```json
+  {
+    "mcpServers": {
+      "common-core": {
+        "url": "https://your-space-name.hf.space/gradio_api/mcp/"
+      }
+    }
+  }
+  ```
+- Screenshots of the MCP client showing the tools available
+
+#### 5. **Setup Instructions**
+
+- Local development setup (if applicable)
+- Environment variables needed
+- Installation steps
+- How to run locally
+
+#### 6. **Visual Documentation**
+
+- **Screenshots or GIFs** of the interface in action
+- Show the Gradio web interface
+- Show MCP client integration (if possible)
+- Demonstrate key features
+
+#### 7. **Demo Video Link (REQUIRED)**
+
+**Must include a link to a demo video that:**
+
+- **Length:** 1-5 minutes
+- **Content Requirements:**
+  - Shows the MCP server **in action**
+  - **Specifically demonstrates integration with an MCP client** (Claude Desktop, Cursor, or similar)
+  - Shows the MCP tools being used through the client
+  - Demonstrates the Gradio web interface
+  - Shows the chat interface using MCP tools
+- **Platform:** YouTube, Vimeo, or other video hosting service
+- **Format:** Include the video link prominently in the README
+
+**Example section:**
+
+```markdown
+## 🎥 Demo Video
+
+Watch the demo video showing the MCP server in action:
+
+[![Demo Video](video-thumbnail-url)](video-url)
+
+The video demonstrates:
+
+- MCP server integration with Claude Desktop
+- Using the Gradio web interface
+- Chat interface with tool calling
+```
+
+#### 8. **Social Media Post Link (REQUIRED)**
+
+**Must include a link to a social media post about the project:**
+
+- Platform: X/Twitter, LinkedIn, or similar
+- Content: Post about your project, the hackathon, and what you built
+- **This link must be included in the README** (not just in submission form)
+- Format: "Share on [Twitter](link) | [LinkedIn](link)"
+
+**Example section:**
+
+```markdown
+## 📱 Social Media
+
+Check out our project announcement:
+
+- [Twitter/X Post](your-twitter-post-url)
+- [LinkedIn Post](your-linkedin-post-url)
+```
+
+#### 9. **Technical Details**
+
+- Architecture overview
+- Technologies used (Gradio 6, MCP, etc.)
+- How the MCP tools work
+- API documentation (if applicable)
+
+#### 10. **Acknowledgments**
+
+- Hackathon organizers
+- Libraries and tools used
+- Any inspiration or references
+
+**README Checklist for Hackathon Submission:**
+
+- [ ] Track tag `building-mcp-track-consumer` included
+- [ ] Team member usernames listed (if team)
+- [ ] Clear project description
+- [ ] Usage instructions for web interface
+- [ ] MCP client integration instructions
+- [ ] Screenshots/GIFs included
+- [ ] Demo video link included (1-5 minutes, shows MCP client integration)
+- [ ] Social media post link included
+- [ ] Setup/installation instructions
+- [ ] Technical details documented
+
+### File Changes Summary
+
+**Files to Create:**
+
+- `app.py`: Main Gradio application with MCP server and chat interface
+- `requirements.txt`: Python dependencies for Hugging Face Space
+- `.env.example`: Environment variable template
+- `README.md`: Updated with hackathon requirements (or update existing)
+
+**Files to Delete:**
+
+- `server.py`: Replaced by `app.py`
+
+**Files to Modify:**
+
+- `pyproject.toml`: Update Gradio to `gradio[mcp]>=6.0.0`, add `huggingface_hub`, remove standalone `mcp` dependency if present
+
+**Files to Reference (Existing):**
+
+- `src/search.py`: Contains `find_relevant_standards_impl()` function
+- `src/lookup.py`: Contains `get_standard_details_impl()` function
+- `src/pinecone_client.py`: Pinecone client implementation
+- `src/mcp_config.py`: Configuration settings
+
+## Technical Specifications (Verified from Documentation)
+
+### Gradio MCP Server Syntax
+
+**Enabling MCP Server:**
+
+```python
+demo.launch(mcp_server=True)
+```
+
+Or via environment variable:
+
+```bash
+export GRADIO_MCP_SERVER=True
+```
+
+**MCP Server Endpoints:**
+
+- Schema: `{base_url}/gradio_api/mcp/schema`
+- SSE Endpoint: `{base_url}/gradio_api/mcp/` (for MCP clients)
+
+### Function Signature Requirements
+
+Functions exposed as MCP tools must:
+
+1. Have type hints for all parameters
+2. Have detailed docstrings with Args and Returns sections
+3. Return a value (not None, unless explicitly typed as `str | None`)
+
+**Example:**
+
+```python
+def find_relevant_standards(
+    activity: str,
+    max_results: int = 5,
+    grade: str | None = None,
+    subject: str | None = None,
+) -> str:
+    """
+    Returns educational standards relevant to the activity.
+
+    Args:
+        activity: Natural language description of the learning activity
+        max_results: Maximum number of standards to return (default: 5)
+        grade: Optional grade level filter (e.g., "K", "01", "05", "09")
+        subject: Optional subject filter (e.g., "Mathematics", "ELA-Literacy")
+
+    Returns:
+        JSON string with structured response containing matching standards
+    """
+    # Implementation
+```
+
+### Repository Structure for Hugging Face Spaces
+
+**Required Files:**
+
+- `app.py` (or `main.py`): Entry point for the Gradio app
+- `requirements.txt`: Python dependencies
+- `README.md`: Project documentation
+
+**Optional but Recommended:**
+
+- `.env.example`: Environment variable template
+- `src/`: Source code directory (already exists)
+
+**Space Configuration:**
+
+- SDK: Set to `gradio` in Hugging Face Space settings
+- Python version: 3.12+ (matches project requirement)
+- Environment variables: Configure in Space settings UI
+
+### Exposing Functions as MCP Endpoints
+
+**Automatic Conversion:**
+
+- Any function passed to `gr.Interface()` or `gr.ChatInterface()` is automatically exposed as an MCP tool
+- Function name becomes the tool name
+- Docstring becomes the tool description
+- Type hints define the parameter schema
+
+**API Name Customization:**
+
+```python
+gr.Interface(
+    fn=find_relevant_standards,
+    # ... inputs and outputs ...
+    api_name="find_relevant_standards",  # Custom API endpoint name
+)
+```
+
+**API Visibility Control:**
+
+```python
+gr.Interface(
+    fn=find_relevant_standards,
+    # ... inputs and outputs ...
+    api_visibility="public",  # "public", "private", or "undocumented"
+)
+```
+
+**API Description Customization:**
+
+```python
+gr.Interface(
+    fn=find_relevant_standards,
+    # ... inputs and outputs ...
+    api_description="Custom description for MCP tool",  # Overrides docstring
+)
+```
+
+## Chat Interface MCP Integration
+
+The chat interface must:
+
+1. Use a Hugging Face model that supports tool calling (e.g., `Qwen/Qwen2.5-7B-Instruct`)
+2. Specify an inference provider (e.g., `provider="together"`) for the model
+3. Handle Gradio 6's structured content format for chat history
+4. Handle tool calling: detect tool requests, execute functions directly, return results to model
+
+**Implementation Notes:**
+
+- The chat interface and MCP tools are in the same Gradio app
+- We call the underlying Python functions directly rather than making HTTP requests to the MCP server
+- The model must be configured to call tools when answering questions about educational standards
+- **Gradio 6 History Format**: Content is now structured as `[{"type": "text", "text": "..."}]` rather than simple strings. The chat function must extract text from these content blocks.
+
+## Testing and Validation
+
+### Local Testing
+
+1. Run `app.py` locally:
+
+   ```bash
+   python app.py
+   ```
+
+2. Verify MCP server is running:
+
+   - Check console output for MCP server URL
+   - Visit `http://localhost:7860/gradio_api/mcp/schema` to view tools
+
+3. Test MCP client connection:
+
+   - Configure Claude Desktop or Cursor to use `http://localhost:7860/gradio_api/mcp/`
+   - Verify tools appear in the client
+
+4. Test chat interface:
+   - Interact with the chat interface in the Gradio UI
+   - Verify it can call MCP tools and return educational standards information
+
+### Hugging Face Space Deployment
+
+1. Push code to Hugging Face Space
+2. Verify Space builds and runs successfully
+3. Check MCP server endpoint: `https://your-space-name.hf.space/gradio_api/mcp/schema`
+4. Test MCP client connection using the Space URL
+5. Test chat interface in the Space UI
+
+## Risks and Assumptions
+
+### Risks
+
+1. **Chat Interface Complexity**: Implementing MCP tool calling with Hugging Face Inference API may be complex and require additional research or libraries.
+
+2. **Model/Provider Availability**: The selected model (`Qwen/Qwen2.5-7B-Instruct`) requires an inference provider (Together AI or Featherless AI). Provider availability and rate limits may affect performance.
+
+3. **MCP Client Configuration**: Users may need guidance on configuring MCP clients to connect to the Space.
+
+4. **Gradio 6 Breaking Changes**: Gradio 6 introduces several breaking changes including structured content format for ChatInterface history. Implementation must handle these changes correctly.
+
+### Assumptions
+
+1. Gradio 6.0.0+ includes all necessary MCP server functionality without additional packages (with `gradio[mcp]` extras).
+
+2. The existing `src/search.py` and `src/lookup.py` implementations can be directly called from Gradio functions without modification.
+
+3. Hugging Face Spaces automatically sets `GRADIO_MCP_SERVER=True` when Gradio 6+ is detected.
+
+4. The MCP server URL format for Hugging Face Spaces is `https://space-name.hf.space/gradio_api/mcp/`.
+
+5. The `Qwen/Qwen2.5-7B-Instruct` model is available via Together AI or Featherless AI inference providers and supports tool calling.
+
+6. Gradio 6 ChatInterface passes history in structured content format that must be parsed to extract text content.
+
+## Dependencies
+
+- **Gradio 6.0.0+**: Required for MCP server support (install with `gradio[mcp]` extras)
+- **Hugging Face Hub/Inference API**: For chat interface model access
+  - Requires `provider="together"` or similar for models that need inference providers
+  - `Qwen/Qwen2.5-7B-Instruct` is available via Together AI and Featherless AI providers
+- **Existing dependencies**: Pinecone, pydantic, etc. (unchanged)
+
+## Deliverables
+
+1. ✅ `app.py`: Gradio application with MCP server and chat interface
+2. ✅ `requirements.txt`: Dependencies for Hugging Face Space
+3. ✅ Updated `README.md`: Hackathon-compliant documentation with all required elements
+4. ✅ `.env.example`: Environment variable template
+5. ✅ Updated `pyproject.toml`: Gradio 6.0.0+ dependency with MCP extras
+6. ✅ Deleted `server.py`: Old FastMCP implementation removed
+7. ✅ Working Hugging Face Space: Deployed in MCP-1st-Birthday organization
+8. ✅ Chat interface: Functional with MCP tool calling
+9. ✅ Demo video: 1-5 minutes showing MCP client integration
+10. ✅ Social media post: Link included in README
+
+## Hackathon Submission Checklist
+
+**Before Submission Deadline (November 30, 2025, 11:59 PM UTC):**
+
+### Registration (Complete Before Building)
+
+- [ ] Joined MCP-1st-Birthday organization on Hugging Face
+- [ ] Completed official registration form
+- [ ] All team members joined organization and registered (if team)
+
+### Technical Implementation
+
+- [ ] `app.py` created with Gradio MCP server
+- [ ] `requirements.txt` includes all dependencies
+- [ ] Space deployed and functional in MCP-1st-Birthday organization
+- [ ] MCP server accessible at `/gradio_api/mcp/` endpoint
+- [ ] Chat interface working with tool calling
+- [ ] All MCP tools (`find_relevant_standards`, `get_standard_details`) functional
+
+### Documentation (README.md)
+
+- [ ] Track tag `building-mcp-track-consumer` included
+- [ ] Team member usernames listed (if team)
+- [ ] Clear project description and purpose
+- [ ] Usage instructions for Gradio web interface
+- [ ] MCP client integration instructions with configuration example
+- [ ] Setup/installation instructions
+- [ ] Screenshots or GIFs included
+- [ ] **Demo video link included** (1-5 minutes, shows MCP client integration)
+- [ ] **Social media post link included**
+- [ ] Technical details documented
+
+### Demo Video Requirements
+
+- [ ] Video length: 1-5 minutes
+- [ ] Shows MCP server in action
+- [ ] **Demonstrates integration with MCP client** (Claude Desktop, Cursor, etc.)
+- [ ] Shows MCP tools being used through the client
+- [ ] Shows Gradio web interface
+- [ ] Shows chat interface using MCP tools
+- [ ] Video hosted on YouTube, Vimeo, or similar
+- [ ] Link included in README
+
+### Social Media Post
+
+- [ ] Post created on X/Twitter, LinkedIn, or similar
+- [ ] Post mentions the project and hackathon
+- [ ] Link included in README (not just submission form)
+
+### Space Configuration
+
+- [ ] Space created in `MCP-1st-Birthday` organization
+- [ ] SDK set to `gradio`
+- [ ] Python version 3.12+
+- [ ] Environment variables configured (PINECONE_API_KEY, HF_TOKEN, etc.)
+- [ ] Space is accessible and functional
+
+### Quality Checks
+
+- [ ] Code follows best practices
+- [ ] Error handling implemented
+- [ ] UI is polished and intuitive
+- [ ] Documentation is clear and complete
+- [ ] All features work as expected
+
+## Next Steps After Sprint
+
+1. **Create Demo Video**:
+
+   - Record 1-5 minute video showing MCP client integration
+   - Demonstrate all key features
+   - Upload to YouTube or Vimeo
+   - Add link to README
+
+2. **Create Social Media Post**:
+
+   - Post about the project on X/Twitter or LinkedIn
+   - Include project highlights and hackathon information
+   - Add link to README
+
+3. **Final README Polish**:
+
+   - Ensure all required elements are present
+   - Add screenshots/GIFs
+   - Verify all links work
+   - Check formatting and clarity
+
+4. **Submit to Hackathon**:
+
+   - Verify all checklist items are complete
+   - Submit before November 30, 2025, 11:59 PM UTC
+   - Engage with community (Discord, Space discussions)
+
+5. **Future Enhancements** (Post-Hackathon):
+   - Fine-tune chat interface model selection and configuration
+   - Add error handling and user feedback improvements
+   - Consider adding more MCP tools or resources
+   - Optimize performance and user experience

.agent/specs/003_gradio/tasks.md

@@ -0,0 +1,76 @@
+# Spec Tasks
+
+## Tasks
+
+- [x] 1. Update Dependencies in pyproject.toml
+
+  - [x] 1.1 Update Gradio dependency from `gradio>=5.0.0,<6.0.0` to `gradio[mcp]>=6.0.0` to enable MCP server support
+  - [x] 1.2 Add `huggingface_hub` to dependencies list for Inference API access in chat interface
+  - [x] 1.3 Remove standalone `mcp` package dependency (FastMCP is no longer used, Gradio 6 includes MCP support)
+  - [x] 1.4 Verify all other dependencies remain unchanged (pinecone, python-dotenv, typer, requests, rich, loguru, pydantic>=2.0.0, pydantic-settings>=2.0.0)
+
+- [x] 2. Create app.py with MCP Tool Wrapper Functions
+
+  - [x] 2.1 Create `app.py` in project root with imports: `gradio as gr`, `find_relevant_standards_impl` from `src.search`, `get_standard_details_impl` from `src.lookup`
+  - [x] 2.2 Implement `find_relevant_standards()` function with signature: `(activity: str, max_results: int = 5, grade: str | None = None, subject: str | None = None) -> str`
+  - [x] 2.3 Add comprehensive docstring to `find_relevant_standards()` following spec format with Args and Returns sections, including all grade level codes and subject examples
+  - [x] 2.4 Add input handling: convert empty string `grade` and `subject` to `None`, convert `max_results` float to int (Gradio Number returns float)
+  - [x] 2.5 Implement `get_standard_details()` function with signature: `(standard_id: str) -> str`
+  - [x] 2.6 Add comprehensive docstring to `get_standard_details()` following spec format with Args, Returns, and Raises sections
+  - [x] 2.7 Delegate both functions to their respective `_impl` functions from `src/` modules
+
+- [x] 3. Create Gradio Interface Structure with TabbedInterface
+
+  - [x] 3.1 Create `gr.Interface` for `find_relevant_standards` with inputs: `gr.Textbox` (activity), `gr.Number` (max_results, min=1, max=20, value=5), `gr.Dropdown` (grade with choices including empty string), `gr.Textbox` (subject, optional)
+  - [x] 3.2 Configure `find_relevant_standards` interface with `gr.JSON` output, title "Find Relevant Standards", description, and `api_name="find_relevant_standards"`
+  - [x] 3.3 Create `gr.Interface` for `get_standard_details` with `gr.Textbox` input (standard_id) and `gr.JSON` output
+  - [x] 3.4 Configure `get_standard_details` interface with title "Get Standard Details", description, and `api_name="get_standard_details"`
+  - [x] 3.5 Create `gr.ChatInterface` with `fn=chat_with_standards` (placeholder for now), `type="messages"`, title, description, and example prompts
+  - [x] 3.6 Combine all three interfaces into `gr.TabbedInterface` with tab labels: ["Search", "Lookup", "Chat"]
+  - [x] 3.7 Add `if __name__ == "__main__": demo.launch(mcp_server=True)` to enable MCP server
+
+- [x] 4. Implement Chat Interface with Hugging Face Inference API
+
+  - [x] 4.1 Add imports to `app.py`: `os`, `json`, `InferenceClient` from `huggingface_hub`
+  - [x] 4.2 Initialize `InferenceClient` with `provider="together"` and `token=os.environ.get("HF_TOKEN")` at module level
+  - [x] 4.3 Define `TOOLS` list with OpenAI function calling format schemas for `find_relevant_standards` and `get_standard_details` matching the function signatures
+  - [x] 4.4 Create `AVAILABLE_FUNCTIONS` dict mapping function names to their `_impl` implementations
+  - [x] 4.5 Implement `chat_with_standards(message: str, history: list) -> str` function signature
+  - [x] 4.6 Add Gradio 6 history format conversion: extract text from structured content blocks `[{"type": "text", "text": "..."}]` format
+  - [x] 4.7 Build message list with system message, converted history, and current user message
+  - [x] 4.8 Implement tool calling workflow: initial API call with tools, detect tool_calls, execute functions, add results, get final response
+  - [x] 4.9 Add error handling with try/except returning user-friendly error messages
+  - [x] 4.10 Configure API calls: model `"Qwen/Qwen2.5-7B-Instruct"`, `tool_choice="auto"`, `temperature=0.7`, `max_tokens=1000`
+
+- [x] 5. Create requirements.txt for Hugging Face Space Deployment
+
+  - [x] 5.1 Create `requirements.txt` in project root
+  - [x] 5.2 Extract dependencies from `pyproject.toml` or manually specify: `gradio[mcp]>=6.0.0`, `pinecone`, `python-dotenv`, `pydantic>=2.0.0`, `pydantic-settings>=2.0.0`, `huggingface_hub`
+  - [x] 5.3 Ensure `[mcp]` extra is included in Gradio dependency specification
+  - [x] 5.4 Verify all required dependencies for both MCP server and chat interface are included
+
+- [x] 6. Create .env.example Template File
+
+  - [x] 6.1 Create `.env.example` in project root
+  - [x] 6.2 Add `PINECONE_API_KEY=your_api_key_here` with comment explaining Pinecone API key requirement
+  - [x] 6.3 Add `PINECONE_INDEX_NAME=common-core-standards` with default value
+  - [x] 6.4 Add `PINECONE_NAMESPACE=standards` with default value
+  - [x] 6.5 Add `HF_TOKEN=your_huggingface_token_here` with comment explaining Hugging Face token requirement for chat interface
+  - [x] 6.6 Add comment noting that `MCP_SERVER_URL` is not needed since functions are called directly
+
+- [x] 7. Create README.md with Code and Documentation Sections
+
+  - [x] 7.1 Create `README.md` in project root with hackathon track tag `building-mcp-track-consumer` in frontmatter or badge format
+  - [x] 7.2 Add project title and description explaining the MCP server purpose, capabilities, and target users (teachers, students, parents)
+  - [x] 7.3 Add team information section (placeholder for username if solo, or format for team members)
+  - [x] 7.4 Add "Usage Instructions" section with subsection A: Gradio Web Interface usage, tab descriptions, and example queries
+  - [x] 7.5 Add subsection B: MCP Client Integration instructions with MCP server URL format, step-by-step configuration, example JSON config, and note about screenshots
+  - [x] 7.6 Add "Setup Instructions" section with local development setup, environment variables, installation steps, and how to run locally
+  - [x] 7.7 Add "Technical Details" section with architecture overview, technologies used (Gradio 6, MCP), how MCP tools work, and API documentation references
+  - [x] 7.8 Add "Visual Documentation" section placeholder noting screenshots/GIFs should be added (but do not create actual media files)
+  - [x] 7.9 Add "Acknowledgments" section with hackathon organizers, libraries/tools used, and inspiration/references
+  - [x] 7.10 Add placeholder sections for "Demo Video" and "Social Media" with note that links will be added separately (exclude from code tasks)
+
+- [x] 8. Delete Old FastMCP server.py File
+  - [x] 8.1 Delete `server.py` from project root (replaced by `app.py`)
+  - [x] 8.2 Verify no other files reference `server.py` that would break

.cursor/commands/{spec_draft.md → draft_spec.md}

@@ -1,37 +1,38 @@
 I am working on developing a comprehensive spec document for the next development sprint.
 
 <goal>
-Solidify the current spec_draft document into a comprehensive specification for the next development sprint through iterative refinement. 
+Solidify the current spec document into a comprehensive specification for the next development sprint through iterative refinement.
 
 The spec draft represents the rough notes and ideas for the next sprint. These notes are likely incomplete and require additional details and decisions to obtain sufficient information to move forward with the sprint.
 
-READ: @.cursor/commands/finalize_spec.md to see the complete requirements for the finalized spec. The goal is to reach the level of specificity and clarity required to create this final spec. 
+READ: `<finalized_spec_requirements>` to see the complete requirements for the finalized spec. The goal is to reach the level of specificity and clarity required to create this final spec.
 </goal>
 
 <process>
 <overview>
-    Iteratively carry out the following steps to progressively refine the requirements for this sprint. Use `Requests for Input` only to gather information that cannot be inferred from the user's selection of a Recommendation; do not ask to confirm details already specified by a selected option. The initial `spec_draft` may be a loose assortment of notes, ideas, and thoughts; treat it accordingly in the first round.
+
+    Iteratively carry out the following steps to progressively refine the requirements for this sprint. Use `Requests for Input` only to gather information that cannot be inferred from the user's selection of a Recommendation; do not ask to confirm details already specified by a selected option. The initial spec draft may be a loose assortment of notes, ideas, and thoughts; treat it accordingly in the first round.
 
     First round: produce a response that includes Recommendations and Requests for Input. The user will reply by selecting exactly one option per Recommendation (or asking for refinement if none fit) and answering only those questions that cannot be inferred from selected options.
 
-    After each user response: update the `spec_draft` to incorporate the selected options with minimal, focused edits. Remove any conflicting or superseded information made obsolete by the selection. Avoid unrelated formatting or editorial changes.
+    After each user response: update the spec draft to incorporate the selected options with minimal, focused edits. Remove any conflicting or superseded information made obsolete by the selection. Avoid unrelated formatting or editorial changes.
+
+    Repeat this back-and-forth until ambiguity is removed and the draft aligns with the requirements in `<finalized_spec_requirements>`.
 
-    Repeat this back-and-forth until ambiguity is removed and the draft aligns with the requirements in `@.cursor/commands/finalize_spec.md`.
 </overview>
 
 <steps>
-    - READ the spec_draft.
+    - READ the spec draft.
     - IDENTIFY anything in the spec draft that is confusing, conflicting, unclear, or missing. Identify important decisions that need to be made.
     - REVIEW the current state of the project to fully understand how these new requirements fit into what already exists.
+    - RESEARCH any technical questions, library options, or implementation approaches that need to be resolved. Conduct this research during spec development so that specific, concrete guidance can be included in the final spec rather than leaving research tasks for the implementer.
     - RECOMMEND specific additions or updates to the draft spec to resolve confusion, add clarity, fill gaps, or add specificity. Recommendations may provide a single option when appropriate or multiple options when needed. Each Recommendation expects selection of one and only one option by the user.
     - ASK targeted questions to acquire details, decisions, or preferences from the user.
-    - APPLY the user's selections: make minimal, localized edits to the `spec_draft` to incorporate the chosen options and remove conflicting content. Incorporate all information contained in the selected options; do not omit details. Do not change unrelated text, structure, or formatting.
+    - APPLY the user's selections: make minimal, localized edits to the spec draft to incorporate the chosen options and remove conflicting content. Incorporate all information contained in the selected options; do not omit details. Do not change unrelated text, structure, or formatting.
     - REFINE: if the user rejects the provided options, revise the Recommendations based on feedback and repeat selection and apply.
 </steps>
 
-<end_conditions>
-    - Continue this process until the draft is unambiguous and conforms to `@.cursor/commands/finalize_spec.md`, or the user directs you to do otherwise.
-    - Do not stop after a single round unless the draft already satisfies all requirements in `@.cursor/commands/finalize_spec.md`.
+<end_conditions> - Continue this process until the draft is unambiguous and conforms to `<finalized_spec_requirements>`, or the user directs you to do otherwise. - Do not stop after a single round unless the draft already satisfies all requirements in `<finalized_spec_requirements>`.
 </end_conditions>
 </process>
 
@@ -42,6 +43,7 @@ READ: @.cursor/commands/finalize_spec.md to see the complete requirements for th
     Using incrementing section numbers are essential for helping the user quickly reference specific options or questions in their responses.
     Responses must strictly follow the Format section. Include only the specified sections and no additional commentary or subsections.
     The agent is responsible for updating the spec draft after each user response.
+
 </overview>
 
 <guidelines>
@@ -52,7 +54,7 @@ READ: @.cursor/commands/finalize_spec.md to see the complete requirements for th
     - Do not ask confirmation questions about facts stated by options; assume the selected option is authoritative.
     - Use numbered sections that increment.
     - Use incrementing decimals for recommendation options and request for input questions.
-    - After the user selects options, apply minimal, focused edits to the `spec_draft` reflecting only those selections. Remove conflicting or superseded content. Avoid broad formatting or editorial changes to unrelated content.
+    - After the user selects options, apply minimal, focused edits to the spec draft reflecting only those selections. Remove conflicting or superseded content. Avoid broad formatting or editorial changes to unrelated content.
     - Do not clutter options or questions with information already clear and unambiguous from the current draft.
     - Do not add subsections beyond those defined in the Format.
 </guidelines>
@@ -60,7 +62,9 @@ READ: @.cursor/commands/finalize_spec.md to see the complete requirements for th
 <format>
 
 # Recommendations
+
 ## 1: Section Title
+
 Short overview providing background on the section.
 
 **Option 1.1**
@@ -70,16 +74,20 @@ Specifics of the first option.
 Specifics of the second option.
 
 ## 2: Section Title
+
 Short overview providing background on the section.
 
 **Option 2.1**
 Specifics of the first option.
 
 # Request for Input
+
 ## 3: Section Title
+
 Short overview providing background on the section.
 
 **Questions**
+
 - 3.1 Some question.
 - 3.2 Another question.
 
@@ -99,14 +107,10 @@ Short overview providing background on the section.
 7 Directions that indicate the users preference in response to the question.
 8 Clear directive in response to the question.
 ```
+
 </user_selection_format>
 
-<selection_and_editing_rules>
-    - One and only one option must be selected per Recommendation. If none fit, request refinement.
-    - Apply edits narrowly: change only text directly impacted by the chosen option(s).
-    - Incorporate all information from the selected options into the draft.
-    - Remove or rewrite conflicting statements made obsolete by the selection.
-    - Preserve unrelated content and overall formatting; do not perform wide editorial passes.
+<selection_and_editing_rules> - One and only one option must be selected per Recommendation. If none fit, request refinement. - Apply edits narrowly: change only text directly impacted by the chosen option(s). - Incorporate all information from the selected options into the draft. - Remove or rewrite conflicting statements made obsolete by the selection. - Preserve unrelated content and overall formatting; do not perform wide editorial passes.
 </selection_and_editing_rules>
 </response>
 
@@ -115,8 +119,41 @@ Short overview providing background on the section.
 </guardrails>
 
 <finalize_spec_compliance_checklist>
-- [ ] All information required by @.cursor/commands/finalize_spec.md is present.
+
+- [ ] All information required by `<finalized_spec_requirements>` are present.
 - [ ] Requirements are testable and unambiguous.
+- [ ] All research completed and findings documented in the spec.
+- [ ] All decisions made and documented; no decision-making left for the implementer.
+- [ ] No research tasks or decision points left for the implementer (or explicitly documented as blockers).
 - [ ] Risks, dependencies, and assumptions captured.
 - [ ] Approval received.
-</finalize_spec_compliance_checklist>
+
+</finalize_spec_compliance_checklist>
+
+<finalized_spec_requirements>
+The spec acts as the comprehensive source of truth for this sprint and should include all the necessary context and technical details to implement this sprint. It should leave no ambiguity for important details necessary to properly implement the changes required.
+
+The spec.md will act as a reference for an LLM coding agent responsible for completing this sprint.
+
+The spec must not include any directions for the implementer to conduct research or make decisions. All research must be completed during spec development, and all decisions must be made and documented in the spec. If there are pending decisions or research that cannot be completed during spec development, these must be explicitly documented as blockers or prerequisites that prevent implementation from proceeding.
+
+The spec should include the following information if applicable:
+
+- An overview of the changes implemented in this sprint.
+- User stories for the new functionality, if applicable.
+- An outline of any new data models proposed.
+- An other technical details determined in the spec_draft or related conversations.
+- Specific filepaths for files for any files that need to be added, edited, or deleted as part of this sprint.
+- Specific files or modules relevant to this sprint.
+- Details on how things should function such as a function, workflow, or other process.
+- Describe what any new functions, services, ect. are supposed to do.
+- Any reasoning or rationale behind decisions, preferences, or changes that provides context for the sprint and its changes.
+- Any other information required to properly understand this sprint, the desired changes, the expected deliverables, or important technical details.
+
+Strive to retain all the final decisions and implementation details provided in the spec draft and related conversations. Cleaning and organizing these raw notes is desirable, but do not exclude or leave out information provided in the spec draft if it is relevant to this sprint. If there is information in the spec draft that is outdated and negated or revised by further direction in the draft or related conversation, you should leave that stale information out of the final spec.
+
+The spec should have all the information a junior developer needs to complete this sprint. They should be able to independently find answers to any questions they have about this sprint and how to implement it in this document. The spec defines exactly what should be implemented and how; it does not require the implementer to make decisions or conduct research. All technical research, library selection, design decisions, and implementation approaches must be resolved and documented in the spec before implementation begins.
+
+**Code Examples in Specs:**
+Use code examples sparingly and only when they provide clarity that text cannot achieve. Keep examples small and focused on specific scenarios, usage patterns, or situations that are difficult to express concisely in prose. Prefer code examples when they are more explicit or concise than equivalent text descriptions. Avoid code examples for obvious implementations or concepts that can be clearly explained in bullet points or brief text. If explicitly directed, longer code examples are appropriate. The guiding principle is to maintain a balance of conciseness, precision, and comprehensiveness—choose the format (code or text) that best achieves this balance.
+</finalized_spec_requirements>

.cursor/commands/finalize_spec.md

@@ -1,21 +0,0 @@
-Convert the spec_draft document into a final draft in the spec.md file.
-
-The spec acts as the comprehensive source of truth for this sprint and should include all the necessary context and technical details to implement this sprint. It should leave no ambiguity for important details necessary to properly implement the changes required.
-
-The spec.md will act as a reference for an LLM coding agent responsible for completing this sprint.
-
-The spec should include the following information if applicable:
-- An overview of the changes implemented in this sprint.
-- User stories for the new functionality, if applicable.
-- An outline of any new data models proposed.
-- An other technical details determined in the spec_draft or related conversations.
-- Specific filepaths for files for any files that need to be added, edited, or deleted as part of this sprint.
-- Specific files or modules relevant to this sprint.
-- Details on how things should function such as a function, workflow, or other process.
-- Describe what any new functions, services, ect. are supposed to do.
-- Any reasoning or rationale behind decisions, preferences, or changes that provides context for the sprint and its changes.
-- Any other information required to properly understand this sprint, the desired changes, the expected deliverables, or important technical details.
-
-Strive to retain all the final decisions and implementation details provided in the spec_draft and related conversations. Cleaning and organizing these raw notes is desirable, but do not exclude or leave out information provided in the spec_draft if it is relevant to this sprint. If there is information in the spec_draft that is outdated and negated or revised by further direction in the draft or related conversation, you should leave that stale information out of the final spec.
-
-The spec should have all the information a junior developer needs to complete this sprint. They should be able to independently find answers to any questions they have about this sprint and how to implement it in this document.

.cursor/rules/standards/code_style/readme.mdc

@@ -0,0 +1,99 @@
+---
+description: Guidelines for writing README documents.
+alwaysApply: false
+---
+
+# README Generation Rules
+
+You are an expert technical writer and software engineer. When asked to write, update, or critique a README.md, adhere strictly to the following principles, style guide, and structure.
+
+## 1. Core Principles
+
+- **The 15-Minute Rule:** The primary goal is to minimize "Time-to-Hello-World." A user must be able to install and run the project (or a specific example) within 15 minutes.
+- **Truth Over Fluff:** NEVER hallucinate features. If a feature is planned, put it in a "Roadmap" section. If code does not exist to support a claim, do not write it.
+- **Inverted Pyramid:** Place the most critical information (What is it? How do I run it?) at the top.
+
+## 2. Tone & Style Guidelines
+
+- **No Marketing Fluff:** DELETE adjectives like "seamless," "easy," "robust," "blazing fast," "state-of-the-art," and "comprehensive." Let the code prove its value.
+- **Active Voice:** Use the imperative mood.
+  - _Bad:_ "The script can be run by the user..."
+  - _Good:_ "Run the script..."
+- **Present Tense:** Avoid "will."
+  - _Bad:_ "Clicking save will write the file."
+  - _Good:_ "Click save. The system writes the file."
+- **Second Person:** Address the user as "you" (implied).
+- **Concrete & Specific:**
+  - _Bad:_ "Requires a database."
+  - _Good:_ "Requires PostgreSQL v14+ running on port 5432."
+
+## 3. Formatting Standards (Markdown)
+
+- **Semantic Headers:** DO NOT skip header levels (e.g., jumping from H1 to H3).
+- **Code Blocks:**
+  - ALWAYS use fenced code blocks (three backticks) with a language identifier (e.g., `bash, `python).
+  - NEVER use indentation (4 spaces) for code blocks.
+- **Inline Code:** Use single backticks for: filenames, directories, variable names, methods, and boolean values (`true`/`false`). Do not bold these.
+- **Lists:**
+  - Use hyphens `-` for bullet points.
+  - Use `1.` for ALL numbered list items (Markdown renders the order automatically).
+- **Alerts:** Use GitHub-standard alert syntax:
+  ```markdown
+  > [!NOTE]
+  > text
+  ```
+- **Links:** Use descriptive link text. Never use "click here."
+
+## 4. Structural Template & Logic
+
+Determine if the project is a **Library** (code used by other code) or an **Application** (standalone tool).
+
+### Section 1: The Hook (Required)
+
+- **H1:** Project Name.
+- **Description:** ONE paragraph.
+  1.  What is it? (Concrete noun).
+  2.  What problem does it solve?
+  3.  Why is it distinct? (Metrics, not adjectives).
+- **Bad Description:** "A holistic solution for data."
+- **Good Description:** "A Python library that converts CSV to JSON without loading the file into memory."
+
+### Section 2: Visuals (Required)
+
+- Include a placeholder for a screenshot, GIF, or terminal output.
+- `![Description of visual content](relative/path/to/image.png)`
+
+### Section 3: Installation & Usage (Context Dependent)
+
+**IF LIBRARY (e.g., npm, pip):**
+
+1.  **Install:** `pip install package-name`
+2.  **Quick Start:** Provide a "Copy-Paste" block.
+    - MUST be a self-contained code snippet that actually runs.
+    - MUST use real API method names found in the context.
+    - DO NOT use generic placeholders like `foo` or `bar` unless necessary.
+
+**IF APPLICATION (e.g., Web App, CLI):**
+
+1.  **Prerequisites:** Strict list (e.g., "Node v18+", "Docker").
+2.  **Setup:**
+    ```bash
+    git clone [repo]
+    npm install
+    cp .env.example .env
+    npm run start
+    ```
+
+### Section 4: Deep Dive (Optional but Recommended)
+
+- **Configuration:** Env variables, flags.
+- **Architecture:** High-level diagram explanation (if complex).
+- **Roadmap:** Planned features (clearly marked as "Future").
+
+## 5. "AI-Proofing" Verification Checklist
+
+Before finalizing the output, perform these checks:
+
+1.  **Hallucination Check:** Do the installation commands actually exist in the codebase (e.g., is there a `requirements.txt` or `package.json` matching the install instructions)?
+2.  **API Check:** Do the methods used in the "Quick Start" match the actual function definitions in the provided files?
+3.  **Adverb Purge:** Remove all adverbs ending in "ly" (e.g., "automatically," "intuitively") unless essential for technical accuracy.

.env.example

@@ -1,7 +1,13 @@
-# Common Standards Project API Configuration
-CSP_API_KEY=your_generated_api_key_here
-
 # Pinecone Configuration
-PINECONE_API_KEY=your_pinecone_api_key_here
+# Get your API key from https://app.pinecone.io/
+PINECONE_API_KEY=your_api_key_here
 PINECONE_INDEX_NAME=common-core-standards
 PINECONE_NAMESPACE=standards
+
+# Hugging Face Configuration
+# Get your token from https://huggingface.co/settings/tokens
+# Required for chat interface Inference API access
+HF_TOKEN=your_huggingface_token_here
+
+# Note: MCP_SERVER_URL is not needed since we call functions directly
+# The MCP server is automatically exposed by Gradio when mcp_server=True

app.py

@@ -0,0 +1,419 @@
+"""Gradio MCP server for Common Core Standards search and lookup."""
+
+import os
+import json
+from typing import Any
+
+from dotenv import load_dotenv
+import gradio as gr
+from huggingface_hub import InferenceClient
+
+# Load environment variables from .env file
+load_dotenv()
+
+from src.search import find_relevant_standards_impl
+from src.lookup import get_standard_details_impl
+
+# Initialize the Hugging Face Inference Client
+# Use HF_TOKEN from environment (automatically available in Hugging Face Spaces)
+# Provider is required for models that need Inference Providers (e.g., Together AI, Nebius)
+HF_TOKEN = os.environ.get("HF_TOKEN")
+client = InferenceClient(
+    provider="together",  # Required: specifies the inference provider for tool calling
+    token=HF_TOKEN
+)
+
+# Define the function schemas in OpenAI format for the model
+TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "find_relevant_standards",
+            "description": "Searches for educational standards relevant to a learning activity using semantic search. Use this when the user asks about standards for a specific activity, lesson, or educational objective.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "activity": {
+                        "type": "string",
+                        "description": "A natural language description of the learning activity, lesson, or educational objective. Be specific and descriptive."
+                    },
+                    "max_results": {
+                        "type": "integer",
+                        "description": "Maximum number of standards to return (1-20). Default is 5.",
+                        "default": 5,
+                        "minimum": 1,
+                        "maximum": 20
+                    },
+                    "grade": {
+                        "type": "string",
+                        "description": "Optional grade level filter. Valid values: K, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, or 09-12 for high school range.",
+                        "enum": ["K", "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "09-12"]
+                    }
+                },
+                "required": ["activity"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_standard_details",
+            "description": "Retrieves complete metadata and content for a specific educational standard by its GUID (_id field). Use this when you have the exact GUID from a previous search result. This function ONLY accepts GUIDs, not statement notations or other identifiers. For searching by content or notation, use find_relevant_standards instead.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "standard_id": {
+                        "type": "string",
+                        "description": "The standard's GUID (_id field) - must be a valid GUID format (e.g., 'EA60C8D165F6481B90BFF782CE193F93'). This function does NOT accept statement notations or other identifier formats."
+                    }
+                },
+                "required": ["standard_id"]
+            }
+        }
+    }
+]
+
+def find_relevant_standards(
+    activity: str,
+    max_results: int = 5,
+    grade: str | None = None,
+) -> str:
+    """
+    Searches for educational standards relevant to a learning activity using semantic search.
+
+    This function performs a vector similarity search over the Common Core Standards database
+    to find standards that match the described learning activity. Results are ranked by relevance
+    and can be filtered by grade level.
+
+    Args:
+        activity: A natural language description of the learning activity, lesson, or educational
+            objective. Examples: "teaching fractions to third graders", "reading comprehension
+            activities", "solving quadratic equations". This is the primary search query and should
+            be descriptive and specific for best results.
+
+        max_results: The maximum number of standards to return. Must be between 1 and 20.
+            Default is 5. Higher values return more results but may include less relevant matches.
+
+        grade: Optional grade level filter. Must be one of the following valid grade level codes:
+            - "K" for Kindergarten
+            - "01" for Grade 1
+            - "02" for Grade 2
+            - "03" for Grade 3
+            - "04" for Grade 4
+            - "05" for Grade 5
+            - "06" for Grade 6
+            - "07" for Grade 7
+            - "08" for Grade 8
+            - "09" for Grade 9
+            - "10" for Grade 10
+            - "11" for Grade 11
+            - "12" for Grade 12
+            - "09-12" for high school range (when standards span multiple high school grades)
+
+            If None or empty string, no grade filtering is applied and standards from all grade
+            levels may be returned. The grade filter uses exact matching against the education_levels
+            metadata field in the database.
+
+    Returns:
+        A JSON string containing a structured response with the following format:
+        {
+            "success": true|false,
+            "results": [
+                {
+                    "_id": "standard_guid",
+                    "content": "full standard text with hierarchy",
+                    "subject": "Mathematics",
+                    "education_levels": ["03"],
+                    "statement_notation": "3.NF.A.1",
+                    "standard_set_title": "Grade 3",
+                    "score": 0.85
+                },
+                ...
+            ],
+            "message": "Found N matching standards" or error message,
+            "error_type": null or error type if success is false
+        }
+
+        On success, the results array contains up to max_results standards, sorted by relevance
+        score (highest first). Each result includes the full standard content, metadata, and
+        relevance score. On error, success is false and an error message describes the issue.
+    """
+    # Handle empty string from dropdown (convert to None)
+    if grade == "":
+        grade = None
+
+    # Ensure max_results is an integer (gr.Number returns float by default)
+    max_results = int(max_results)
+
+    return find_relevant_standards_impl(activity, max_results, grade)
+
+
+def get_standard_details(standard_id: str) -> str:
+    """
+    Retrieves complete metadata and content for a specific educational standard by its GUID.
+
+    This function performs a direct lookup using the standard's GUID (_id field) only.
+    It does NOT accept statement notations, ASN identifiers, or any other identifier formats.
+    Use find_relevant_standards to search for standards by content or metadata.
+
+    Args:
+        standard_id: The standard's GUID (_id field) - must be a valid GUID format
+            (e.g., "EA60C8D165F6481B90BFF782CE193F93"). This is the GUID returned in
+            search results from find_relevant_standards.
+
+    Returns:
+        A JSON string containing a structured response with the following format:
+        {
+            "success": true|false,
+            "results": [
+                {
+                    "_id": "standard_guid",
+                    "content": "full standard text with hierarchy",
+                    "subject": "Mathematics",
+                    "education_levels": ["03"],
+                    "statement_notation": "3.NF.A.1",
+                    "standard_set_title": "Grade 3",
+                    "asn_identifier": "S21238682",
+                    "depth": 3,
+                    "is_leaf": true,
+                    "parent_id": "parent_guid",
+                    "ancestor_ids": [...],
+                    "child_ids": [...],
+                    ... (all available metadata fields)
+                }
+            ],
+            "message": "Retrieved standard details" or error message,
+            "error_type": null or error type if success is false
+        }
+
+        On success, the results array contains exactly one standard object with all available
+        metadata fields including hierarchy relationships, content, and identifiers. On error
+        (e.g., standard not found), success is false and the message provides guidance, such as
+        suggesting to use find_relevant_standards for searching.
+
+    Raises:
+        This function does not raise exceptions. All errors are returned as JSON responses
+        with success=false and appropriate error messages.
+    """
+    return get_standard_details_impl(standard_id)
+
+
+def chat_with_standards(message: str, history: list):
+    """
+    Chat function that uses MCP tools via Hugging Face Inference API with tool calling.
+
+    This function integrates with Qwen2.5-7B-Instruct to answer questions about educational
+    standards. The model can call find_relevant_standards and get_standard_details tools
+    to retrieve information and provide accurate responses.
+
+    Args:
+        message: The user's current message/query
+        history: Chat history in Gradio 6 messages format. Each message is a dict with
+            "role" and "content" keys. In Gradio 6, content uses structured format:
+            [{"type": "text", "text": "..."}, ...] for text content.
+
+    Returns:
+        Structured content as a list of content blocks. When tool calls are made, includes:
+        - Expandable JSON blocks showing tool call results
+        - The final assistant response as text
+        When no tool calls are made, returns a simple text response.
+    """
+    # Convert Gradio 6 history format to OpenAI messages format
+    # Gradio 6 uses structured content: {"role": "user", "content": [{"type": "text", "text": "..."}]}
+    messages = []
+    if history:
+        for msg in history:
+            if isinstance(msg, dict):
+                role = msg.get("role", "user")
+                content = msg.get("content", "")
+
+                # Handle Gradio 6 structured content format
+                if isinstance(content, list):
+                    # Extract text from content blocks
+                    text_parts = []
+                    for block in content:
+                        if isinstance(block, dict) and block.get("type") == "text":
+                            text_parts.append(block.get("text", ""))
+                    content = " ".join(text_parts)
+
+                messages.append({
+                    "role": role,
+                    "content": content
+                })
+
+    # Add system message to guide the model
+    system_message = {
+        "role": "system",
+        "content": "You are a helpful assistant for parents and teachers. Your role is to help them plan educational activities and find educational requirements for activities they might have already done. You have access to tools that can search for standards and retrieve standard details. Use these tools when users ask about standards, learning activities, or educational requirements. Always provide clear, helpful responses based on the tool results."
+    }
+
+    # Add current user message
+    messages.append({"role": "user", "content": message})
+
+    # Prepare full message list with system message
+    full_messages = [system_message] + messages
+
+    try:
+        # Initial API call with tools
+        response = client.chat.completions.create(
+            model="Qwen/Qwen2.5-7B-Instruct",
+            messages=full_messages,
+            tools=TOOLS,
+            tool_choice="auto",  # Let the model decide when to call functions
+            temperature=0.7,
+            max_tokens=1000,
+        )
+
+        response_message = response.choices[0].message
+
+        # Check if model wants to call functions
+        if response_message.tool_calls:
+            # Add assistant's tool call request to messages
+            full_messages.append(response_message)
+
+            # Store tool call results for display
+            tool_results = []
+
+            # Process each tool call
+            for tool_call in response_message.tool_calls:
+                function_name = tool_call.function.name
+                function_args = json.loads(tool_call.function.arguments)
+
+                # Execute the function
+                if function_name == "find_relevant_standards":
+                    print(f"Finding relevant standards for activity: {function_args.get('activity', '')}")
+                    result = find_relevant_standards_impl(
+                        activity=function_args.get("activity", ""),
+                        max_results=function_args.get("max_results", 5),
+                        grade=function_args.get("grade"),
+                    )
+                elif function_name == "get_standard_details":
+                    print(f"Getting standard details for standard ID: {function_args.get('standard_id', '')}")
+                    result = get_standard_details_impl(
+                        standard_id=function_args.get("standard_id", "")
+                    )
+                else:
+                    result = json.dumps({"error": f"Function {function_name} not available"})
+
+                # Parse result JSON for display
+                try:
+                    result_data = json.loads(result) if isinstance(result, str) else result
+                except json.JSONDecodeError:
+                    result_data = {"raw_result": result}
+
+                # Store tool call info for display
+                tool_results.append({
+                    "function": function_name,
+                    "arguments": function_args,
+                    "result": result_data
+                })
+
+                # Add function result to messages
+                full_messages.append({
+                    "role": "tool",
+                    "tool_call_id": tool_call.id,
+                    "name": function_name,
+                    "content": result,
+                })
+
+            # Get final response with function results
+            final_response = client.chat.completions.create(
+                model="Qwen/Qwen2.5-7B-Instruct",
+                messages=full_messages,
+                temperature=0.7,
+                max_tokens=1000,
+            )
+
+            # Build structured response with tool call results and final answer
+            response_blocks = []
+            
+            # Add tool call results as expandable JSON blocks using markdown
+            for i, tool_result in enumerate(tool_results):
+                # Format arguments and result as pretty JSON
+                args_json = json.dumps(tool_result["arguments"], indent=2)
+                result_json = json.dumps(tool_result["result"], indent=2)
+                
+                # Create collapsible markdown section
+                tool_markdown = f"""<details>
+<summary><strong>🔧 Tool Call: {tool_result["function"]}</strong></summary>
+
+**Arguments:**
+```json
+{args_json}
+```
+
+**Result:**
+```json
+{result_json}
+```
+</details>
+"""
+                response_blocks.append({
+                    "type": "text",
+                    "text": tool_markdown
+                })
+            
+            # Add separator before final response
+            response_blocks.append({
+                "type": "text",
+                "text": "---\n"
+            })
+            
+            # Add final assistant response as text
+            response_blocks.append({
+                "type": "text",
+                "text": final_response.choices[0].message.content
+            })
+
+            return response_blocks
+        else:
+            # No tool calls, return direct response as text
+            return response_message.content
+
+    except Exception as e:
+        # Error handling
+        return f"I apologize, but I encountered an error: {str(e)}. Please try again or rephrase your question."
+
+
+# Create Gradio interface
+demo = gr.TabbedInterface(
+    [
+        gr.ChatInterface(
+            fn=chat_with_standards,  # See complete implementation above
+            title="Chat with Standards",
+            description="Ask questions about educational standards. The AI will use MCP tools to find relevant information.",
+            examples=["What standards apply to teaching fractions in 3rd grade?", "Find standards for reading comprehension"],
+            api_visibility="private",  # Hide from MCP server - only expose search and lookup tools
+        ),
+        gr.Interface(
+            fn=find_relevant_standards,
+            inputs=[
+                gr.Textbox(label="Activity Description", placeholder="Describe a learning activity..."),
+                gr.Number(label="Max Results", value=5, minimum=1, maximum=20),
+                gr.Dropdown(
+                    label="Grade (optional)",
+                    choices=["", "K", "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "09-12"],
+                    value=None,
+                    info="Select a grade level to filter results"
+                ),
+            ],
+            outputs=gr.JSON(label="Results"),
+            title="Find Relevant Standards",
+            description="Search for educational standards relevant to a learning activity.",
+            api_name="find_relevant_standards",
+        ),
+        gr.Interface(
+            fn=get_standard_details,
+            inputs=gr.Textbox(label="Standard ID", placeholder="Enter a standard GUID or identifier..."),
+            outputs=gr.JSON(label="Standard Details"),
+            title="Get Standard Details",
+            description="Retrieve full metadata for a specific standard by its ID.",
+            api_name="get_standard_details",
+        ),
+    ],
+    ["Chat", "Search", "Lookup"],
+)
+
+if __name__ == "__main__":
+    demo.launch(mcp_server=True)
+

pyproject.toml

@@ -3,8 +3,7 @@ name = "common-core-mcp"
 version = "0.1.0"
 requires-python = ">=3.12"
 dependencies = [
-    "mcp",
-    "gradio>=5.0.0,<6.0.0",
+    "gradio[mcp]>=6.0.0",
     "pinecone",
     "python-dotenv",
     "typer",
@@ -13,6 +12,7 @@ dependencies = [
     "loguru",
     "pydantic>=2.0.0",
     "pydantic-settings>=2.0.0",
+    "huggingface_hub",
 ]
 
 [project.optional-dependencies]

requirements.txt

@@ -0,0 +1,11 @@
+gradio[mcp]>=6.0.0
+pinecone
+python-dotenv
+typer
+requests
+rich
+loguru
+pydantic>=2.0.0
+pydantic-settings>=2.0.0
+huggingface_hub
+

src/lookup.py

@@ -0,0 +1,81 @@
+"""Direct ID lookup implementation for educational standards."""
+
+from __future__ import annotations
+
+import json
+
+from pinecone.exceptions import PineconeException
+
+from src.pinecone_client import PineconeClient
+
+
+def get_standard_details_impl(standard_id: str) -> str:
+    """
+    Implementation of direct standard lookup by GUID only.
+
+    This function only accepts GUIDs (_id field) from Pinecone. It does NOT accept
+    statement_notation or other identifier formats. Use find_relevant_standards to
+    search for standards by content or metadata.
+
+    Args:
+        standard_id: The standard's GUID (_id field) - must be a valid GUID format
+            (e.g., "EA60C8D165F6481B90BFF782CE193F93")
+
+    Returns:
+        JSON string with structured response containing standard details
+    """
+    # Input validation
+    if not standard_id or not standard_id.strip():
+        return json.dumps(
+            {
+                "success": False,
+                "results": [],
+                "message": "Standard ID cannot be empty",
+                "error_type": "invalid_input",
+            }
+        )
+
+    try:
+        # Initialize client and fetch standard
+        client = PineconeClient()
+        result = client.fetch_standard(standard_id.strip())
+
+        # Handle not found
+        if result is None:
+            return json.dumps(
+                {
+                    "success": False,
+                    "results": [],
+                    "message": f"Standard with GUID '{standard_id}' not found. This function only accepts GUIDs (e.g., 'EA60C8D165F6481B90BFF782CE193F93'). For statement notations or other identifiers, use find_relevant_standards with a keyword search instead.",
+                    "error_type": "not_found",
+                }
+            )
+
+        # Format successful result
+        response = {
+            "success": True,
+            "results": [result],
+            "message": "Retrieved standard details",
+        }
+
+        return json.dumps(response, indent=2)
+
+    except PineconeException as e:
+        return json.dumps(
+            {
+                "success": False,
+                "results": [],
+                "message": f"Pinecone API error: {str(e)}",
+                "error_type": "api_error",
+            }
+        )
+    except Exception as e:
+        return json.dumps(
+            {
+                "success": False,
+                "results": [],
+                "message": f"Unexpected error: {str(e)}",
+                "error_type": "api_error",
+            }
+        )
+

src/mcp_config.py

@@ -0,0 +1,33 @@
+"""MCP server configuration module."""
+
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class McpSettings(BaseSettings):
+    """Configuration settings for the MCP server."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # Pinecone Configuration
+    pinecone_api_key: str = ""
+    pinecone_index_name: str = "common-core-standards"
+    pinecone_namespace: str = "standards"
+
+
+_settings: McpSettings | None = None
+
+
+def get_mcp_settings() -> McpSettings:
+    """Get the singleton MCP settings instance."""
+    global _settings
+    if _settings is None:
+        _settings = McpSettings()
+    return _settings
+

{tools → src}/pinecone_client.py

@@ -12,10 +12,10 @@ from loguru import logger
 from pinecone import Pinecone
 from pinecone.exceptions import PineconeException
 
-from tools.config import get_settings
+from src.mcp_config import get_mcp_settings
 from tools.pinecone_models import PineconeRecord
 
-settings = get_settings()
+settings = get_mcp_settings()
 
 
 class PineconeClient:
@@ -205,6 +205,8 @@ class PineconeClient:
             "normalized_subject",
             "publication_status",
             "parent_id",  # Must be omitted when None (Pinecone doesn't accept null)
+            "document_id",
+            "document_valid",
         }
         for field in optional_fields:
             if record_dict.get(field) is None:
@@ -212,6 +214,103 @@ class PineconeClient:
 
         return record_dict
 
+    def search_standards(
+        self,
+        query_text: str,
+        top_k: int = 5,
+        grade: str | None = None,
+    ) -> list[dict]:
+        """
+        Perform semantic search over standards.
+
+        Args:
+            query_text: Natural language query
+            top_k: Maximum number of results
+            grade: Optional grade filter
+
+        Returns:
+            List of result dictionaries with metadata and scores
+        """
+        # Build filter dictionary dynamically
+        # Always filter to only leaf nodes (actual standards, not parent categories)
+        filter_parts = [{"is_leaf": {"$eq": True}}]
+        
+        if grade:
+            filter_parts.append({"education_levels": {"$in": [grade]}})
+
+        filter_dict = None
+        if len(filter_parts) == 1:
+            filter_dict = filter_parts[0]
+        elif len(filter_parts) == 2:
+            filter_dict = {"$and": filter_parts}
+
+        # Build query dictionary
+        query_dict: dict[str, Any] = {
+            "inputs": {"text": query_text},
+            "top_k": top_k * 2,  # Get more candidates for reranking
+        }
+        if filter_dict:
+            query_dict["filter"] = filter_dict
+
+        # Call search with reranking
+        results = self.index.search(
+            namespace=self.namespace,
+            query=query_dict,
+            rerank={"model": "bge-reranker-v2-m3", "top_n": top_k, "rank_fields": ["content"]},
+        )
+
+        # Parse results
+        hits = results.get("result", {}).get("hits", [])
+        parsed_results = []
+        for hit in hits:
+            result_dict = {
+                "_id": hit["_id"],
+                "score": hit["_score"],
+                **hit.get("fields", {}),
+            }
+            parsed_results.append(result_dict)
+
+        return parsed_results
+
+    def fetch_standard(self, standard_id: str) -> dict | None:
+        """
+        Fetch a standard by its GUID (_id field only).
+
+        This method performs a direct lookup using Pinecone's fetch() API, which only
+        works with the standard's GUID (_id field). It does NOT search by statement_notation,
+        asn_identifier, or any other metadata fields.
+
+        Args:
+            standard_id: Standard GUID (_id field) - must be the exact GUID format
+                (e.g., "EA60C8D165F6481B90BFF782CE193F93")
+
+        Returns:
+            Standard dictionary with metadata, or None if not found
+        """
+        result = self.index.fetch(ids=[standard_id], namespace=self.namespace)
+
+        # Extract vectors from FetchResponse
+        # FetchResponse.vectors is a dict mapping ID to Vector objects
+        vectors = result.vectors
+        
+        if not vectors or standard_id not in vectors:
+            return None
+
+        vector = vectors[standard_id]
+        
+        # Extract metadata from Vector object
+        # Vector has: id, values (embedding), and metadata (dict with all fields)
+        metadata = vector.metadata or {}
+        vector_id = vector.id
+
+        # Combine _id with all metadata fields
+        record_dict = {
+            "_id": vector_id,
+            **metadata,
+        }
+
+        return record_dict
+
     @staticmethod
     def is_uploaded(set_dir: Path) -> bool:
         """

src/search.py

@@ -0,0 +1,86 @@
+"""Semantic search implementation for educational standards."""
+
+from __future__ import annotations
+
+import json
+
+from pinecone.exceptions import PineconeException
+
+from src.pinecone_client import PineconeClient
+
+
+def find_relevant_standards_impl(
+    activity: str,
+    max_results: int = 5,
+    grade: str | None = None,
+) -> str:
+    """
+    Implementation of semantic search over educational standards.
+
+    Args:
+        activity: Description of the learning activity
+        max_results: Maximum number of standards to return (default: 5)
+        grade: Optional grade level filter (e.g., "K", "01", "05", "09")
+
+    Returns:
+        JSON string with structured response containing matching standards
+    """
+    # Input validation
+    if not activity or not activity.strip():
+        return json.dumps(
+            {
+                "success": False,
+                "results": [],
+                "message": "Activity description cannot be empty",
+                "error_type": "invalid_input",
+            }
+        )
+
+    try:
+        # Initialize client and perform search
+        client = PineconeClient()
+        results = client.search_standards(
+            query_text=activity.strip(),
+            top_k=max_results,
+            grade=grade,
+        )
+
+        # Handle empty results
+        if not results:
+            return json.dumps(
+                {
+                    "success": False,
+                    "results": [],
+                    "message": "No matching standards found",
+                    "error_type": "no_results",
+                }
+            )
+
+        # Format successful results
+        response = {
+            "success": True,
+            "results": results,
+            "message": f"Found {len(results)} matching standards",
+        }
+
+        return json.dumps(response, indent=2)
+
+    except PineconeException as e:
+        return json.dumps(
+            {
+                "success": False,
+                "results": [],
+                "message": f"Pinecone API error: {str(e)}",
+                "error_type": "api_error",
+            }
+        )
+    except Exception as e:
+        return json.dumps(
+            {
+                "success": False,
+                "results": [],
+                "message": f"Unexpected error: {str(e)}",
+                "error_type": "api_error",
+            }
+        )
+

tools/cli.py

@@ -470,7 +470,7 @@ def pinecone_init():
     Uses integrated embeddings with llama-text-embed-v2 model.
     """
     try:
-        from tools.pinecone_client import PineconeClient
+        from src.pinecone_client import PineconeClient
 
         console.print("[bold]Initializing Pinecone...[/bold]")
 
@@ -555,7 +555,7 @@ def pinecone_upload(
     If neither is provided, you'll be prompted to confirm uploading all sets.
     """
     try:
-        from tools.pinecone_client import PineconeClient
+        from src.pinecone_client import PineconeClient
         from tools.pinecone_models import ProcessedStandardSet
         import json
 

tools/pinecone_models.py

@@ -31,8 +31,8 @@ class PineconeRecord(BaseModel):
     subject: str
     normalized_subject: str | None = None
     education_levels: list[str]
-    document_id: str
-    document_valid: str
+    document_id: str | None = None
+    document_valid: str | None = None
     publication_status: str | None = None
     jurisdiction_id: str
     jurisdiction_title: str