feat(mcp): add mcp-aura package for model context protocol integration

[rokasta12]

🚀 Pull Request

Thank you for contributing to AURA Protocol! Your contribution helps build a more open, interoperable web.

📋 Description

What does this PR do?

• Adds a new mcp-aura package that implements Model Context Protocol (MCP) integration for AURA
• Provides a bridge between MCP-compatible AI agents (like Claude Desktop) and AURA-enabled websites
• Enables AI agents to discover and execute capabilities on AURA sites through standardized MCP tools

Why is this change needed?

• MCP is becoming a standard for AI agent tool integration
• This allows AURA sites to be accessible to any MCP-compatible AI agent without custom integration
• Provides a reference implementation for other MCP-AURA bridges

How does this change work?

• AuraAdapter handles low-level AURA protocol communication (manifest fetching, cookie management, state tracking)
• MCP Handler provides a thin abstraction layer with caching and batch processing
• MCP Server exposes AURA capabilities as MCP tools that agents can discover and use

🎯 Type of Change

• ✨ New feature (non-breaking change that adds functionality)
• 🧪 Test addition/improvement
• 📚 Documentation update (changes to documentation only)

📦 Package Impact

• @aura/protocol (Core TypeScript interfaces and JSON Schema)
• reference-server (Next.js reference implementation)
• reference-client (Example client with LLM integration)
• CLI tools (aura-validate)
• Documentation
• Multiple packages
• Project infrastructure

New package added: mcp-aura

🔗 Related Issues

N/A - New feature addition

🧪 Testing

Test Coverage:

• All existing tests pass
• New tests added for new functionality
• Tests cover edge cases
• Manual testing performed

Testing Performed:

• Unit tests: 21 tests for AuraAdapter core functionality
• Integration tests: 27 tests for end-to-end workflows
• Manual testing: Test agent validates all scenarios from step.md
• Cross-platform testing: Tested on macOS with Node.js

Test Commands:

Run unit tests

pnpm --filter mcp-aura test:unit

Run integration tests (requires reference server)

pnpm --filter mcp-aura test:integration

Run test agent

pnpm --filter mcp-aura test:agent

📖 Documentation

• Code comments updated/added
• README.md updated
• Package-specific documentation updated
• API documentation updated
• Examples updated/added
• No documentation changes needed

✅ Checklist

Code Quality:

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings or errors
• I have added tests that prove my fix is effective or that my feature works

Protocol Compliance:

• Changes maintain backward compatibility (or breaking changes are clearly documented)
• JSON Schema updated if TypeScript interfaces changed
• URI Template/JSON Pointer compliance maintained (RFC 6570, RFC 6901)
• Reference implementations updated to reflect protocol changes

Project Standards:

• My commits have descriptive messages
• I have updated the version numbers appropriately (if applicable)
• I have checked that my changes don't break existing functionality

🔄 Breaking Changes

Is this a breaking change?

• Yes, this introduces breaking changes
• No, this is backward compatible

🎪 Use Cases & Examples

Example Usage:
// Direct usage
import { AuraAdapter } from 'mcp-aura';

const adapter = new AuraAdapter('http://localhost:3000');
await adapter.connect();
const result = await adapter.execute('login', {
email: 'user@example.com',
password: 'password123'
});

// MCP Handler usage
import { handleMCPRequest } from 'mcp-aura';

const response = await handleMCPRequest({
siteUrl: 'http://localhost:3000',
capabilityId: 'create_post',
args: { title: 'Test', content: 'Content' }
});

Benefits:

• Any MCP-compatible AI agent can now interact with AURA sites
• Automatic session management and state tracking
• Batch request processing for efficiency
• Full RFC compliance for URI templates and JSON Pointers

📊 Performance Impact

• No performance impact
• Performance improvement (describe)
• Potential performance impact (describe and justify)

Adapter instances are cached per site to avoid redundant connections.

🌍 Community Impact

Who benefits from this change?

• New AURA users
• Experienced implementers
• Framework integrators
• Tool builders
• All users

Community Considerations:

• Provides a reference implementation for MCP integration
• Makes AURA accessible to the growing MCP ecosystem
• Enables AI agents to interact with AURA sites without custom code

🔒 Security Considerations

• No security implications
• Security improvement
• Potential security impact (describe)

Uses standard cookie-based session management with tough-cookie library.

📝 Additional Notes

Implementation Details:

• Uses @modelcontextprotocol/sdk for MCP server implementation
• Implements full AURA protocol spec including state management
• Provides comprehensive test coverage including edge cases

Future Considerations:

• Add request caching/memoization for performance
• Implement rate limiting client-side
• Add metrics and observability features

---

🤝 Contributor Agreement

By submitting this pull request, I confirm that:

• I have read and agree to follow the project's Code of Conduct
• I have read the Contributing Guidelines
• My contribution is licensed under the MIT License
• I understand that my contribution may be used in derivative works

---

Thank you for contributing to AURA Protocol! 🚀

Building a more open, interoperable web together.