@graphite-atlas/mcp-server 1.0.0

package/EXAMPLES.md

@@ -0,0 +1,501 @@
+# Graphite Atlas MCP Server - Usage Examples
+
+Real-world examples of using the Graphite Atlas MCP server with Claude Desktop.
+
+## Basic Atlas Operations
+
+### Creating a Knowledge Graph
+
+**User**: "Create a new atlas called 'Product Research' for tracking competitive analysis"
+
+**Claude** will use:
+- Tool: `create_atlas`
+- Parameters: `{ name: "Product Research", description: "Competitive analysis tracking" }`
+
+**Result**: New atlas created with ID returned
+
+---
+
+### Listing Your Atlases
+
+**User**: "What atlases do I have?"
+
+**Claude** will use:
+- Tool: `list_atlases`
+
+**Response**:
+```
+You have 3 atlases:
+1. Product Research (ID: atlas-123)
+   - Competitive analysis tracking
+   - Created: 2025-12-15
+
+2. Meeting Notes (ID: atlas-456)
+   - Weekly team meeting summaries
+   - Created: 2025-12-10
+
+3. Reading List (ID: atlas-789)
+   - Books and articles to read
+   - Created: 2025-12-01
+```
+
+---
+
+## Building a Knowledge Graph
+
+### Adding Points (Entities)
+
+**User**: "In my Product Research atlas, add these companies: Anthropic, OpenAI, and Google DeepMind"
+
+**Claude** will use `create_point` three times:
+```javascript
+create_point({
+  atlas_id: "atlas-123",
+  name: "Anthropic",
+  type: "Company",
+  properties: { founded: "2021", focus: "AI Safety" }
+})
+
+create_point({
+  atlas_id: "atlas-123",
+  name: "OpenAI",
+  type: "Company",
+  properties: { founded: "2015", focus: "AGI Research" }
+})
+
+create_point({
+  atlas_id: "atlas-123",
+  name: "Google DeepMind",
+  type: "Company",
+  properties: { founded: "2010", focus: "AI Research" }
+})
+```
+
+---
+
+### Creating Relationships
+
+**User**: "Add a 'competes_with' relationship between Anthropic and OpenAI"
+
+**Claude** will use `create_path`:
+```javascript
+create_path({
+  atlas_id: "atlas-123",
+  name: "competes with",
+  type: "COMPETES_WITH",
+  source_id: "point-abc",  // Anthropic
+  target_id: "point-def",  // OpenAI
+  properties: { market: "Enterprise AI", intensity: "high" }
+})
+```
+
+---
+
+## AI-Powered Graph Generation (Brain Dump)
+
+### Convert Meeting Notes to Graph
+
+**User**: "Take these meeting notes and add them to my Meeting Notes atlas:
+
+Team Sync - Dec 19, 2025
+Attendees: Alice (PM), Bob (Eng), Carol (Design)
+
+Alice presented the new user dashboard feature. Bob raised concerns about API rate limits. Carol showed mockups for the mobile view. We decided to prioritize the API optimization first, then implement the dashboard.
+
+Action items:
+- Bob: Investigate caching strategy
+- Carol: Finalize mobile designs
+- Alice: Update roadmap
+"
+
+**Claude** will use `brain_dump`:
+```javascript
+brain_dump({
+  atlas_id: "atlas-456",
+  text: "[meeting notes]",
+  process_name: "Team Sync Dec 19"
+})
+```
+
+**Expected Graph** (AI-generated):
+- **Points**:
+  - Alice (Person, role: PM)
+  - Bob (Person, role: Engineer)
+  - Carol (Person, role: Designer)
+  - User Dashboard (Feature)
+  - API Rate Limits (Issue)
+  - Mobile View (Design)
+  - Caching Strategy (Task, owner: Bob)
+  - Mobile Designs (Task, owner: Carol)
+  - Roadmap Update (Task, owner: Alice)
+
+- **Paths**:
+  - Alice → PRESENTED → User Dashboard
+  - Bob → RAISED → API Rate Limits
+  - Carol → SHOWED → Mobile View
+  - API Optimization → BLOCKS → User Dashboard
+  - Bob → ASSIGNED_TO → Caching Strategy
+  - etc.
+
+---
+
+## Search and Discovery
+
+### Finding Related Information
+
+**User**: "In my Product Research atlas, find all points related to 'AI safety'"
+
+**Claude** will use `search_points`:
+```javascript
+search_points({
+  atlas_id: "atlas-123",
+  query: "AI safety"
+})
+```
+
+**Response**:
+```
+Found 5 points related to "AI safety":
+1. Anthropic (Company) - Focus: AI Safety
+2. Constitutional AI (Concept)
+3. RLHF (Technique) - Used for alignment
+4. AI Safety Research (Category)
+5. Alignment Problem (Challenge)
+```
+
+---
+
+## Complex Workflows
+
+### Building a Product Comparison
+
+**User**: "I want to compare Claude, GPT-4, and Gemini. Create a comparison graph in my Product Research atlas."
+
+**Claude** will:
+
+1. Create company points:
+```javascript
+create_point({ name: "Anthropic", type: "Company" })
+create_point({ name: "OpenAI", type: "Company" })
+create_point({ name: "Google", type: "Company" })
+```
+
+2. Create product points:
+```javascript
+create_point({
+  name: "Claude",
+  type: "AI Model",
+  properties: {
+    context_window: "200K tokens",
+    strengths: "Long context, helpful",
+    release_date: "2023"
+  }
+})
+
+create_point({
+  name: "GPT-4",
+  type: "AI Model",
+  properties: {
+    context_window: "128K tokens",
+    strengths: "Versatile, powerful",
+    release_date: "2023"
+  }
+})
+
+create_point({
+  name: "Gemini",
+  type: "AI Model",
+  properties: {
+    context_window: "1M tokens",
+    strengths: "Multimodal, fast",
+    release_date: "2023"
+  }
+})
+```
+
+3. Create relationships:
+```javascript
+create_path({
+  name: "develops",
+  type: "DEVELOPS",
+  source_id: "anthropic_id",
+  target_id: "claude_id"
+})
+
+create_path({
+  name: "develops",
+  type: "DEVELOPS",
+  source_id: "openai_id",
+  target_id: "gpt4_id"
+})
+
+create_path({
+  name: "develops",
+  type: "DEVELOPS",
+  source_id: "google_id",
+  target_id: "gemini_id"
+})
+```
+
+---
+
+## Data Management
+
+### Updating Information
+
+**User**: "Update the Claude point to reflect that the context window is now 500K tokens"
+
+**Claude** will use `update_point`:
+```javascript
+update_point({
+  atlas_id: "atlas-123",
+  point_id: "point-claude",
+  properties: {
+    context_window: "500K tokens"
+  }
+})
+```
+
+---
+
+### Bulk Operations
+
+**User**: "Add tags to all AI model points in my Product Research atlas with tag 'LLM'"
+
+**Claude** will:
+
+1. List all points: `list_points({ atlas_id: "atlas-123" })`
+2. Filter AI models
+3. Update each with tag:
+```javascript
+update_point({
+  atlas_id: "atlas-123",
+  point_id: "point-claude",
+  properties: { tags: ["LLM"] }
+})
+// Repeat for GPT-4, Gemini, etc.
+```
+
+---
+
+## Visualization and Analysis
+
+### Getting Graph Statistics
+
+**User**: "How many points and relationships are in my Product Research atlas?"
+
+**Claude** will:
+
+1. List points: `list_points({ atlas_id: "atlas-123" })`
+2. List paths: `list_paths({ atlas_id: "atlas-123" })`
+
+**Response**:
+```
+Your Product Research atlas contains:
+- 47 points (entities)
+- 82 paths (relationships)
+
+Breakdown by type:
+Points:
+- 12 Companies
+- 18 Products
+- 10 Concepts
+- 7 People
+
+Paths:
+- 25 DEVELOPS relationships
+- 20 COMPETES_WITH relationships
+- 15 USES relationships
+- 12 RELATED_TO relationships
+- 10 FOUNDED_BY relationships
+```
+
+---
+
+## Advanced Use Cases
+
+### Research Paper Analysis
+
+**User**: "I just read this AI safety paper. Add it to my Reading List atlas and extract key concepts:
+
+[Paste abstract of AI alignment paper...]
+"
+
+**Claude** will use `brain_dump` to:
+- Create point for the paper
+- Extract key concepts (alignment, reward hacking, value learning, etc.)
+- Create relationships between concepts
+- Link authors to the paper
+
+---
+
+### Project Planning
+
+**User**: "Help me plan a new project called 'Mobile App Redesign' in my Product Research atlas"
+
+**Claude** will create a project graph:
+
+1. Main project point:
+```javascript
+create_point({
+  name: "Mobile App Redesign",
+  type: "Project",
+  properties: {
+    status: "Planning",
+    deadline: "Q2 2026",
+    priority: "High"
+  }
+})
+```
+
+2. Feature points:
+- User Authentication
+- Dark Mode
+- Offline Support
+- Push Notifications
+
+3. Dependencies:
+- Authentication → BLOCKS → Dark Mode
+- Dark Mode → BLOCKS → Offline Support
+
+4. Team members:
+- Alice (PM) → OWNS → Mobile App Redesign
+- Bob (Eng) → WORKS_ON → User Authentication
+- Carol (Design) → WORKS_ON → Dark Mode
+
+---
+
+## Integration Patterns
+
+### Daily Standup Notes
+
+**User**: "Convert today's standup notes to my Meeting Notes atlas"
+
+Use brain_dump regularly to build a historical graph of:
+- What team members worked on
+- Blockers and dependencies
+- Decisions made
+- Action items
+
+Over time, this builds a searchable knowledge base of your team's work.
+
+---
+
+### Personal Knowledge Management
+
+Use multiple atlases:
+- **Daily Notes**: Brain dump daily journal entries
+- **Reading**: Track books, articles, papers with brain dump
+- **Projects**: Manually curate project structure
+- **People**: Network graph of contacts and relationships
+
+Ask Claude:
+- "What did I work on last week?" (search Meeting Notes)
+- "Who do I know at Google?" (search People atlas)
+- "What papers have I read about transformers?" (search Reading atlas)
+
+---
+
+## Tips and Best Practices
+
+### 1. Use Descriptive Names
+
+**Good**:
+```javascript
+create_point({
+  name: "Claude 3.5 Sonnet",
+  type: "AI Model",
+  properties: { version: "3.5", variant: "Sonnet" }
+})
+```
+
+**Bad**:
+```javascript
+create_point({
+  name: "Model 1",
+  type: "Thing"
+})
+```
+
+### 2. Consistent Relationship Types
+
+Use ALL_CAPS for relationship types to match graph database conventions:
+- `WORKS_AT`
+- `KNOWS`
+- `DEPENDS_ON`
+- `PART_OF`
+
+### 3. Leverage Properties
+
+Store rich metadata in properties:
+```javascript
+create_point({
+  name: "Research Paper: Attention is All You Need",
+  type: "Paper",
+  properties: {
+    authors: ["Vaswani", "Shazeer", "Parmar"],
+    year: 2017,
+    citations: 85000,
+    url: "https://arxiv.org/abs/1706.03762",
+    tags: ["transformers", "attention", "NLP"]
+  }
+})
+```
+
+### 4. Use Brain Dump for Speed
+
+Instead of manually creating points and paths, use brain_dump for:
+- Meeting notes
+- Articles/papers
+- Brainstorming sessions
+- Interview transcripts
+
+Then refine manually if needed.
+
+### 5. Regular Searches
+
+Don't just add data—query it!
+- "What concepts am I tracking about AI safety?"
+- "Show me all the projects blocked by API work"
+- "Which people are connected to the mobile app project?"
+
+---
+
+## Troubleshooting Examples
+
+### "I can't find a point I just created"
+
+Try searching:
+```
+"Search for [point name] in my [atlas name] atlas"
+```
+
+If still not found, list all points:
+```
+"List all points in my [atlas name] atlas"
+```
+
+### "Wrong atlas used"
+
+Always specify the atlas:
+```
+"In my Product Research atlas, create a point called..."
+```
+
+Not:
+```
+"Create a point called..."
+```
+
+### "Relationship creation failed"
+
+Check that both points exist first:
+```
+"List points in my atlas and show IDs"
+```
+
+Then create path with correct IDs.
+
+---
+
+**For more examples, see the [Graphite Atlas documentation](https://docs.graphiteatlas.com).**

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Graphite Atlas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.